Skill Authoring — Best Practices in Depth

skills/writing-skills/reference/best-practices.md · view on GitHub

Detail behind the SKILL.md workflow. Read the section you need.

Contents

Conciseness: the context window is a public good

Your skill shares context with the system prompt, conversation history, other skills’ metadata, and the user’s actual request. Only name/description are pre-loaded; the body loads on invocation — but once loaded it stays for the session, so every line is a recurring cost.

Default assumption: Claude is already very smart. Add only what it lacks. Challenge each piece: “Does Claude need this? Can I assume it knows? Does this paragraph justify its tokens?”

Concise (~50 tokens):

## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Too verbose (~150 tokens): a paragraph explaining what PDFs are, that libraries exist, that pdfplumber is one option, how to pip install it… all of which Claude already knows.

Writing effective descriptions

The description is the single most important field — Claude picks among potentially 100+ skills using it alone.

Good:

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Bad: Helps with documents · Processes data · Does stuff with files

Degrees of freedom: match specificity to fragility

Think of Claude as a robot on a path.

Over-constraining an open task wastes tokens and judgment; under-constraining a fragile one causes errors.

Progressive disclosure patterns

SKILL.md is a table of contents that points to detail loaded on demand.

Pattern 1 — High-level guide with references. Quick-start inline; “For form filling, see FORMS.md; for the API, see REFERENCE.md.”

Pattern 2 — Domain organization. Split by domain so unrelated domains cost nothing:

bigquery-skill/
├── SKILL.md            # overview + navigation
└── reference/
    ├── finance.md
    ├── sales.md
    └── product.md

A grep -i "revenue" reference/finance.md hint helps Claude jump straight to the right place.

Pattern 3 — Conditional detail. Show the common path inline; link advanced/edge cases (“For tracked changes, see REDLINING.md”).

Keep references one level deep. SKILL.md → file.md is fine; SKILL.md → a.md → b.md is not — Claude may head deeply-nested files and read them incompletely. Add a table of contents to any reference file over ~100 lines so partial reads still reveal full scope.

Workflows, checklists, and feedback loops

For complex multi-step work, give an explicit checklist Claude can copy into its response and tick off:

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate (run validate_fields.py)
- [ ] Step 4: Fill (run fill_form.py)
- [ ] Step 5: Verify (run verify_output.py)

Clear numbered steps stop Claude skipping validation.

Feedback loop: run validator → fix → repeat, and “only proceed when validation passes.” Works with scripts (validate.py) or with a reference doc as the “validator” (compare against STYLE_GUIDE.md). For batch/destructive/high-stakes work, use plan → validate → execute: have Claude write a structured plan file, validate it with a script (verbose, specific errors), then apply.

Scripts and executable code

Pre-written scripts beat regenerated code: more reliable, no code in context, consistent, faster.

For the specific case of wrapping an API with no CLI (a bundled script with abstracted subcommands plus a generic passthrough), see api-wrappers.md.

Content guidelines

Anti-patterns

Evaluation and iteration (Claude A / Claude B)

Build evaluations before extensive docs, so you solve real gaps:

  1. Run representative tasks with no skill; record failures.
  2. Write ~3 concrete test scenarios with expected behaviors.
  3. Measure the baseline.
  4. Write the minimum instructions to pass them.
  5. Iterate against the baseline.

Develop with two roles: Claude A helps you write/refine the skill; a fresh Claude B uses it on real tasks; you observe B’s behavior and bring specifics back to A (“B forgot to filter test accounts even though the skill mentions it — make that rule more prominent”). Watch for: unexpected file-read order (structure unclear), missed references (links not prominent), a file never read (unnecessary or poorly signaled), repeated reads of one file (maybe promote it into SKILL.md). Iterate on observed behavior, not assumptions.

Annotated pre-ship checklist

Core quality

Code & scripts

Testing

Also in writing-skills