Is a 2000‑Line SKILL.md a Prompt or Documentation? Practical Guide for Claude Skills

What is an Agent Skill?

A Skill is a markdown file ( SKILL.md) that records the experience, constraints, and execution order for a class of tasks. The Agent discovers the Skill, loads it on demand, and uses the contained workflow only when the task matches the Skill’s description.

Basic Structure of a Skill

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

The file consists of two parts:

YAML front‑matter – identifies the Skill and defines when it should be used.

Body – concrete workflow, constraints, examples, and failure‑handling rules.

Front‑matter Metadata

Two fields are mandatory: name – a unique identifier (max 64 characters, only lowercase letters, numbers, and hyphens, no XML tags or reserved words such as anthropic or claude). description – a short routing description that tells the Agent what the Skill does and in which scenario it should be loaded.

Good naming examples:

processing-pdfs

reviewing-code

test-driven-development

analyzing-spreadsheets

Poor naming examples (too vague or containing reserved words): helper, utils, documents, anthropic-helper.

The description must be specific enough for the Agent to decide relevance. A good description states both the capability and the trigger scenario, optionally adding common trigger keywords.

Body Content Guidelines

The body should contain only the information the Agent truly needs to execute the task. Avoid encyclopedic introductions or project‑level READMEs. Focus on:

Concrete rules and parameters.

Edge‑case handling.

Checklist items and failure‑handling snippets.

Example of a concise PDF‑extraction body:

## Extract PDF Text

Use <code>pdfplumber</code> to extract text:

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

Contrast with a verbose version that adds background about PDFs and library choices – the extra text consumes context tokens without adding value for the Agent.

Include failure‑handling rules directly, e.g.:

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

Length Limits and Progressive Disclosure

Anthropic recommends keeping the main SKILL.md body under 500 lines. If the Skill grows larger, split detailed sections into separate files under references/ or scripts/ and load them only when needed.

Three‑layer loading strategy:

Advertisement layer – only the front‑matter metadata is loaded initially.

Instruction layer – when the description matches the task, the main body is read.

Resource layer – any referenced files are loaded on demand.

This avoids “context rot” where long contexts dilute important signals.

Controlling the Degree of Freedom

Decide how much autonomy the Agent should have based on task risk:

Low freedom – high‑risk operations (e.g., database migration, production deployment) require exact commands and a strict “do not modify” rule.

Medium freedom – tasks with a fixed template but adjustable parameters.

High freedom – analysis, review, or brainstorming where the Agent can make judgments.

Low‑freedom example (database migration):

## Database Migration

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add extra parameters.
If the command fails, stop execution and return the error output.

High‑freedom example (code review checklist):

## Code Review

1. Obvious bugs or missing edge cases?
2. Security risks?
3. Performance impact?
4. Violation of project conventions?
5. Simpler implementation possible?

Prioritize issues that affect correctness and stability.

Worked Example: Superpowers TDD Skill

Metadata (only two lines):

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

Body (simplified):

## Rule
Write a failing test before production code.
If you did not watch the test fail, the test is not trusted.

## Flow
1. **RED**: Write one small failing test.
2. **VERIFY RED**: Run it. Confirm it fails for the expected reason.
3. **GREEN**: Write the smallest code to pass.
4. **REFACTOR**: Clean up without changing behavior.

## Ask Before Skipping
- Throwaway prototypes
- Generated code

## Done Checklist
- [ ] Test written first
- [ ] Failure observed
- [ ] Minimal code added
- [ ] Tests pass

The TDD Skill enforces a low‑freedom “iron law”:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Verification of the RED stage is mandatory; the Agent must see the test fail for the correct reason before proceeding.

Other Open‑Source Skills

code-review-expert

– detects SOLID violations, security risks, and proposes actionable improvements.

Git commit helper – generates descriptive commit messages from git diff output.

File Organization and Progressive Disclosure

For larger domains, split the Skill into a lightweight main file and detailed reference files. Example for a data‑analysis Skill:

bigquery-analysis/
├── SKILL.md               # overview and navigation
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md

Main file only lists available datasets and links to the corresponding reference files. When a user asks about “sales pipeline”, the Agent loads reference/sales.md and ignores the others, keeping the context small.

Conditional Branching

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

## 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 the file can be opened.

3. Edit workflow
   - Unpack existing document.
   - Modify specified content.
   - Verify after each modification.
   - Re‑package.

If the number of branches grows, keep the main file short and move each detailed flow to separate files under a workflows/ directory.

Designing Workflows and Feedback Loops

Complex tasks should enumerate explicit steps and mandatory verification points. The Superpowers TDD Skill demonstrates this with stages RED → VERIFY RED → GREEN → REFACTOR, each accompanied by a checklist that forces the Agent to pause and confirm the expected state before moving on.

Example verification checklist (generic):

## Verification Checklist

- [ ] Every new function/method has a test
- [ ] Watched each test fail before implementing
- [ ] Each test failed for the expected reason
- [ ] Minimal code added to pass each test
- [ ] All tests pass
- [ ] Output has no errors or warnings

Common Pitfalls

Treating a Skill as a project README – leads to verbose, low‑value content.

Writing an overly large Skill that tries to cover many unrelated tasks – the Agent cannot decide which part to use.

Providing too many tool choices – the Agent may pick inconsistently; give a default and an explicit fallback.

Inconsistent terminology – use the same term throughout to avoid confusion.

Leaving deterministic work (e.g., file processing) to the LLM – delegate to scripts and specify exact error handling.

Key Checklist for a Reliable Skill

Metadata name follows naming rules. description clearly states purpose and trigger scenario.

Body contains only actionable rules, examples, and failure handling.

Main file stays under 500 lines; detailed data lives in referenced files.

Freedom degree matches task risk.

Verification steps are explicit and mandatory.

All external Skills are reviewed for safety before use.

References

Superpowers TDD Skill – https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md

Superpowers repository – https://github.com/obra/superpowers

sanyuan‑skills – https://github.com/sanyuan0704/sanyuan-skills

Anthropic official Skills repository – https://github.com/anthropics/skills