Best practices for writing Claude Code skills, rules, and CLAUDE.md instructions. Use when creating SKILL.md files, authoring .claude/rules, writing CLAUDE.md project or user instructions, or configuring Claude behavior for a project or team.
Guides developers in writing concise, effective Claude skills and rules with concrete examples and anti-patterns.
/plugin marketplace add rileyhilliard/claude-essentials/plugin install ce@claude-essentialsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/rules-and-memory.mdreferences/skills.mdCore principle: The context window is a shared resource. Every token in your skill or rule competes with conversation history, other skills, and the user's actual request. Write the minimum instructions needed to change Claude's behavior from its defaults.
Load the relevant reference based on what you're configuring:
| Configuring... | Load | File |
|---|---|---|
| Skills (SKILL.md files, plugin skills) | Skills | references/skills.md |
| Rules, CLAUDE.md, memory | Rules & Memory | references/rules-and-memory.md |
Load both when creating a plugin that includes skills alongside project-level rules.
These apply whether you're writing a skill, a rule file, or CLAUDE.md instructions.
Only add context Claude doesn't already have. Challenge each piece:
| Good (~50 tokens) | Bad (~150 tokens) |
|---|---|
| "Use pdfplumber for text extraction" + code snippet | "PDF (Portable Document Format) files are a common format..." then background, then library comparison, then code |
Specific instructions produce consistent behavior. Vague guidance produces inconsistent results.
| Concrete | Vague |
|---|---|
Run python scripts/validate.py --input {file} | "Validate the data before proceeding" |
| "Use 2-space indentation, single quotes" | "Format code properly" |
| "Queries return in under 100ms" | "Robust performance" |
Put the most important rules first. Structure content so the highest-priority instructions appear early: opening paragraph, first table, first section heading. Bury critical rules in paragraph 4 and they'll get less attention.
Tables scan faster than prose. Use them for comparisons, decision trees, when-to-use logic, and anti-pattern lists. Reserve prose for reasoning and context that doesn't fit tabular format.
Not every instruction needs the same level of specificity. Match it to how much damage a wrong choice causes.
| Freedom | Use when | Example |
|---|---|---|
| High (text guidance) | Multiple valid approaches, context-dependent | Code review process, documentation style |
| Medium (templates/pseudocode) | Preferred pattern exists, some variation OK | Report generation, API response format |
| Low (exact commands) | Fragile operations, consistency critical | Database migrations, deployment scripts |
Skill descriptions and rule content get injected into system prompts. Inconsistent point-of-view causes discovery problems.
| Pattern | Problem |
|---|---|
| Over-explaining basics Claude already knows | Wastes tokens, dilutes the instructions that matter |
| Vague descriptions ("Helps with projects") | Claude can't determine when to activate the skill |
| Deeply nested references (A -> B -> C) | Claude partially reads files past one level deep |
| Time-sensitive info ("After August 2025...") | Becomes silently wrong, use "current" vs "deprecated" sections |
| Multiple options without a default | Adds decision burden instead of reducing it |
| Instructions buried in prose paragraphs | Critical rules get missed, use headers and tables |
| Inconsistent terminology (mixing "endpoint", "URL", "route") | Confuses Claude about whether these are distinct concepts |
| Em dashes, emojis, corporate speak in instructions | Leaks into Claude's output style |
Skill(ce:writer) with The Engineer persona for technical docs, or The Educator persona for tutorials and onboarding guides.Skill(ce:documenting-systems) when the config involves creating README files, API docs, or architecture documentation.Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.