skill-design

name

skill-design

description

Best-practices guide for designing and auditing Claude Code skills and global configuration. Covers CLAUDE.md length and content fitness, skill naming and description quality, SKILL.md structure and progressive disclosure, trigger condition robustness, settings.json permissions, and directory hygiene. Use whenever asked to write, update, audit, or improve a SKILL.md file; evaluate trigger condition quality; review or suggest improvements to a CLAUDE.md or settings.json; create a new skill from scratch; improve an existing skill; or assess whether skills in a set cross-reference each other correctly.

Designing and auditing Claude skills

Config lives at ~/.claude/ (containing CLAUDE.md, settings.json, and skills/).

Copy this checklist and track progress through each section:

Audit progress:
- [ ] Step 1: Inventory the current state
- [ ] Step 2: CLAUDE.md audit
- [ ] Step 3: Skills audit
- [ ] Step 4: settings.json audit
- [ ] Step 5: Structure and hygiene audit
- [ ] Step 6: Write up findings and proposed changes

---

Principles (the "why" behind every check)

CLAUDE.md is loaded in full at the start of every session — every line costs context every time. Target ≤200 lines. Only include what would cause a mistake if removed.

Skills are loaded on demand when relevant — they are the right place for domain knowledge, setup docs, and reference material that is only sometimes needed. A lean CLAUDE.md + rich skills is the correct trade-off.

settings.json controls what Claude can do without prompting. Pre-approve all safe read-only operations; use hooks for truly deterministic behaviors.

---

Step 1: Inventory

find ~/.claude -type f | sort
wc -l ~/.claude/CLAUDE.md
wc -l ~/.claude/skills/*/SKILL.md
ls -la ~/.claude/skills/

Note the line count of CLAUDE.md and each SKILL.md before proceeding.

---

Step 2: CLAUDE.md audit

For each section, apply this filter:

Question	If NO → action
Must this be loaded in every session?	Candidate for extraction to a skill
Would removing it cause Claude to make a mistake?	Safe to remove or condense
Is this duplicated in a skill that already triggers when relevant?	Remove from CLAUDE.md
Is this setup/installation/maintenance doc?	Move to a dedicated skill

What belongs in CLAUDE.md (universal, session-critical):

• Identity and environment (user, system, groups, scheduler)
• Personal filesystem paths and quota rules
• Formatting and style preferences (docstrings, markdown conventions)
• Working norms (how to handle disagreement, clarification, durable knowledge)
• Token-efficiency behavioral rules
• Short reference tables Claude needs instantly (repos/accounts, filesystem layout)
• Tool gotchas that occur in normal sessions (e.g. qmd negation parser)
• Dotfiles management rules (where to put new files)

What does NOT belong in CLAUDE.md:

• Installation guides or setup scripts for any tool
• Anything only needed when onboarding a new machine
• Long command blocks for rarely-used maintenance operations
• Full paths and masks for every indexed collection (a list of names suffices)
• MCP server architecture explanations
• Anything Claude can infer from reading the code or project files
• Standard language/framework conventions Claude already knows

---

Step 3: Skills audit

For each skill in skills/:

Naming — name field in frontmatter:

• Lowercase letters, numbers, hyphens only (no spaces, no uppercase)
• ≤64 characters
• Gerund form preferred (auditing-config, processing-pdfs) or action-oriented (audit-config, process-pdfs); avoid vague nouns (helper, utils)

Description — description field in frontmatter:

• Written in third person (not "I can..." or "You can use this to...")
• States what the skill does AND when to trigger it (include specific keywords/contexts)
• ≤1024 characters
• Specific enough to distinguish from other skills (avoid "helps with documents")

Trigger condition robustness — the "Use this skill whenever…" clause:

• Lists specific import paths the user would write (import pymaster, from ceci import PipelineStage)
• Lists specific class and function names covered by the skill (NmtWorkspace, decouple_cell, open_input)
• Includes conceptual/task-level triggers that fire before the user knows the API ("asks how to define a pipeline stage", "needs to run a ceci pipeline on NERSC") — not just symbol names
• Covers both code-context triggers (user is writing code with the library) and question-context triggers (user is asking what tool to use or how something works)
• For skills that defer to other skills in some cases, the trigger explicitly names those boundaries ("for NERSC job submission, see the nersc skill") so Claude routes correctly

Body:

• SKILL.md body under 500 lines; split into reference files if approaching the limit
• Uses progressive disclosure: summary/overview in SKILL.md, details in references/ files
• Reference files are linked directly from SKILL.md — no chains (SKILL.md → A → B is too deep)
• Reference files have a table of contents if > 100 lines
• Consistent terminology throughout (pick one term and use it everywhere)
• No time-sensitive information ("before August 2025, use the old API…")
• Complex workflows broken into numbered steps with a copyable checklist
• Scripts and templates referenced explicitly from SKILL.md

Directory hygiene:

• No empty subdirectories
• No web-artifact files (robots.txt, .htaccess, etc.)
• All file paths use forward slashes
• File names are descriptive (form_validation_rules.md, not doc2.md)

---

Step 4: settings.json audit

cat ~/.claude/settings.json

• All commonly-used read-only Bash tools are in permissions.allow (ls, find, grep, cat, head, tail, wc, stat, etc.)
• All MCP tools the user uses are in permissions.allow
• No destructive operations (rm, git reset --hard, force push) are pre-approved
• Git read-only operations (log, status, diff, show, blame) are pre-approved
• If any "must-always-happen" behaviors exist (linting after edits, blocking writes to certain dirs), they are hooks — not just instructions in CLAUDE.md

---

Step 5: Structure and hygiene audit

ls -la ~/.claude/                # check what's a symlink vs real file
ls ~/.claude/skills/    # confirm skill dirs

• ~/.claude/CLAUDE.md → symlink to dotfiles ✓
• ~/.claude/settings.json → symlink to dotfiles ✓
• ~/.claude/skills/ → symlink to dotfiles ✓
• ~/.claude.json is NOT in dotfiles (it's volatile session state) ✓
• Credentials, cache, session data are in ~/.claude/ as regular files, not dotfiles ✓
• Any new skill directories created since last audit are symlinked or are inside the skills/ symlink ✓

---

Step 6: Write up findings

Organize findings into:

1. Critical — CLAUDE.md bloat, broken skill descriptions, missing permissions
2. Moderate — skill naming issues, description quality, long SKILL.md files
3. Minor — empty dirs, stray files, inconsistent terminology

For each proposed change, state:

• What to change and why (which principle it violates)
• Specific files affected
• Estimated line impact on CLAUDE.md (if applicable)

For extraction proposals (moving content from CLAUDE.md to a skill), always propose the new skill's name and description fields.

---

Common anti-patterns

Anti-pattern	Principle violated	Fix
CLAUDE.md > 200 lines	Every line costs context every session	Extract setup/reference docs to skills
Installation guides in CLAUDE.md	Only needed on new machine setup, not every session	Create a dedicated skill
Vague skill description ("helps with documents")	Claude can't distinguish skills by description	Rewrite: third-person, specific, include trigger terms
Trigger mentions only import X	User may not know what to import; misses task-level triggers	Add class/function names AND conceptual triggers ("asks how to…", "needs to…")
Trigger covers only code context, not question context	Skill won't fire when user is asking "which tool should I use?"	Add "asks about…" / "needs to…" triggers alongside symbol-name triggers
First-person skill description ("I can help you...")	Breaks discovery; description is injected into system prompt	Rewrite in third person
Empty directories in skill dirs	Clutter	Delete
Web-artifact files (robots.txt) in skill dirs	Not applicable to local filesystem skills	Delete
References nested > 1 level deep	Claude may partially read nested files	Restructure to link directly from SKILL.md
Duplicate content in CLAUDE.md and a skill	Wastes context; risks divergence	Remove from CLAUDE.md, keep in skill
Style/convention rules Claude already knows	Bloats CLAUDE.md with no benefit	Delete
Time-sensitive dates in skill content	Will become wrong	Use "old patterns" / "legacy" framing instead