configuring-claude

Configuring Claude

Core 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.

Topic Selection

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.

---

Universal Principles

These apply whether you're writing a skill, a rule file, or CLAUDE.md instructions.

Assume competence

Only add context Claude doesn't already have. Challenge each piece:

• "Does Claude need this explanation?"
• "Can I assume Claude knows this?"
• "Does this paragraph justify its token cost?"

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

Be concrete

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"

Lead with the critical stuff

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.

Use tables for decisions

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.

Match freedom to fragility

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

Write in third person

Skill descriptions and rule content get injected into system prompts. Inconsistent point-of-view causes discovery problems.

• Good: "Processes Excel files and generates reports"
• Bad: "I can help you process Excel files"
• Bad: "You can use this to process Excel files"

---

Anti-Patterns

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

---

Cross-References

• Writing tone and style for config content: Load Skill(ce:writer) with The Engineer persona for technical docs, or The Educator persona for tutorials and onboarding guides.
• Documentation: Load Skill(ce:documentation) when the config involves creating README files, API docs, architecture documentation, or auditing code comments.