Is Your 2000‑Line SKILL.md a Prompt or a Manual? Best Practices for Claude Skills

Agent Skills are task‑specific manuals that an LLM can discover and load on demand, allowing the model to reuse team conventions such as code‑review rules, log formats, or API response schemas without hard‑coding them into prompts.

Basic Structure

A minimal Skill consists of a directory containing a SKILL.md file. Optional folders such as scripts/, references/ and assets/ can hold helper scripts, extra documentation, or static templates.

skill-name/
├── SKILL.md          # main file, loaded on trigger
├── scripts/          # utility scripts (executed, not loaded)
├── references/       # reference docs (loaded on demand)
└── assets/           # templates, static files (loaded on demand)

Metadata (Frontmatter)

The frontmatter must contain at least two fields: name and description. name is the identifier used by the system and humans; it must be ≤64 characters, only lowercase letters, numbers and hyphens, and must not contain XML tags or reserved words such as anthropic or claude. Using a gerund (verb‑ing) makes the capability clear, e.g., processing-pdfs. description tells the Agent when the Skill is applicable. It should answer two questions: what the Skill does and in which scenario it should be used. A good description includes trigger keywords (e.g., PDF, form, extraction) to improve both rule‑based and semantic matching.

Good and Bad Naming / Description Examples

Good name: processing-pdfs Bad name: helper, utils (too vague)

Good description: "Extract text and tables from PDF files, fill forms, and merge documents. Use when the task mentions PDF, form, or document extraction."

Bad description: "I can help you process PDF files." (first‑person, no trigger condition)

Writing the Body

The body is the actual executable manual. It should contain only the information the Agent needs to perform the task, not general explanations. Each paragraph should be justified by asking:

Does the Agent really need this explanation?

Is it private knowledge or common sense?

Is it worth consuming context?

Example of a concise body for PDF text extraction:

## Extract PDF Text

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

Contrast with an overly verbose version that repeats what a PDF is and lists many libraries – this adds noise and harms the Agent’s focus.

Checklists and Pitfalls

Include concrete, non‑obvious rules that the Agent cannot infer, e.g., soft‑delete conventions:

users table uses soft delete. All production queries must include `WHERE deleted_at IS NULL`.

Avoid generic statements like "soft delete is a common technique" because they waste context.

Length Limits and Progressive Disclosure

Anthropic recommends keeping the main SKILL.md under 500 lines. If more detail is needed, split it into separate files under references/ or scripts/ and load them only when the Agent decides they are required.

Three‑layer loading model:

Advertisement layer: only name and description are loaded at startup.

Command layer: when the description matches the task, the Agent loads the main SKILL.md body.

Resource layer: the Agent loads referenced scripts or docs on demand.

Freedom Levels

Decide how much autonomy the Agent should have:

High freedom: tasks that require judgment (e.g., code review) – provide direction, not exact steps.

Medium freedom: templated tasks with adjustable parameters – give a template and allowed bounds.

Low freedom: high‑risk operations (database migration, production deployment) – hard‑code exact commands and forbid modifications.

Example of low‑freedom TDD skill:

# NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

### RED – Write Failing Test
Write one minimal test that demonstrates the desired behavior.

### VERIFY RED – Watch It Fail
- Test must fail, not error.
- Failure reason must match the expected missing feature.

### GREEN – Minimal Code
Write the smallest code to pass the test.

### REFACTOR – Clean Up
Remove duplication, improve names, extract helpers.

## Verification Checklist
- [ ] Every new function has a test
- [ ] Test failure observed before implementation
- [ ] Each test fails for the expected reason
- [ ] Minimal code added to pass each test
- [ ] All tests pass
- [ ] No errors or warnings in output

Workflow and Feedback Loops

Complex tasks need explicit step order and verification points. Write each stage as a checklist and make verification mandatory before proceeding.

Example code‑review workflow:

## Code Review Process
1. Get changed file list and diff
2. First round – design review
   - Check overall architecture
   - Check SOLID violations
   - Report major design issues before detailed review
3. Second round – implementation review
   - Look for security risks (SQL injection, XSS, privilege escalation)
   - Identify performance hotspots (DB calls in loops, missing indexes)
   - Verify exception handling and edge cases
4. Output findings
   - Tag severity: Critical / Warning / Suggestion
   - Provide actionable fix suggestions

Conditional Branches

When a Skill must handle multiple scenarios, write explicit branches instead of leaving the Agent to guess.

## Document Modification Workflow
1. Determine task type
   **Create new document?** → follow creation workflow
   **Edit existing document?** → follow edit workflow
2. Creation workflow
   - Use template to generate document
   - Export to target format
   - Verify file opens correctly
3. Edit workflow
   - Unpack existing document
   - Apply specified changes
   - Verify after each change
   - Re‑package document

Limit Choices

Provide a default solution and a fallback rather than a list of alternatives. For PDF extraction, recommend pdfplumber as the default and fall back to OCR with pdf2image + pytesseract only for scanned PDFs.

Consistent Terminology

Use the same term throughout a Skill (e.g., always “API endpoint” instead of mixing “URL”, “route”, “path”) to avoid ambiguity for the model.

Delegate Deterministic Work to Scripts

Let the LLM decide, but let scripts perform exact operations such as file I/O, calculations, or batch processing. Example of robust file handling:

# Recommended: explicit error handling
def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"File {path} not found, creating empty file")
        with open(path, "w") as f:
            f.write("")
        return ""

Final Checklist

Write a precise description that states what the Skill does and when to use it.

Keep the body focused on actionable steps, constraints, and edge‑case handling.

Limit the main file to ~500 lines; move details to references/ or scripts/.

Adjust freedom level according to risk: high‑risk tasks get fixed commands, low‑risk tasks get guidance.

Insert verification checkpoints and checklists to prevent the Agent from skipping essential steps.

Review third‑party Skills before adoption to ensure they contain no unsafe commands.

Images