configuring-claude
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.
What this skill does
# 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:writer)` with The Engineer persona when the config involves creating README files, API docs, architecture documentation, or auditing code comments.
Related in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.