---
topic: agentskills-skill-authoring
source_keys:
  - agentskills-best-practices
---

## Start from real expertise

A common pitfall: asking an LLM to generate a skill without domain-specific context. The result is vague, generic procedures rather than the specific API patterns, edge cases, and project conventions that make a skill valuable.

**Extract from a hands-on task.** Complete a real task in conversation with an agent, providing corrections and preferences along the way. Then extract the reusable pattern. Capture:
- Steps that worked — the sequence that led to success
- Corrections you made — "use library X not Y," "check for edge case Z"
- Input/output formats — what data looked like going in and out
- Context you provided — project-specific facts the agent didn't know

**Synthesize from existing artifacts.** Feed project-specific material into an LLM and ask it to synthesize a skill. Good sources: internal runbooks, API specs, code review comments, version control history (especially patches — reveals patterns through what actually changed), real-world failure cases.

## Refine with real execution

Run the skill against real tasks. Feed results — all of them, not just failures — back into the creation process. Even a single execute-then-revise pass noticeably improves quality.

Read agent execution traces, not just final outputs. Common causes of wasted work in traces:
- Instructions too vague — agent tries multiple approaches
- Instructions that don't apply to the current task — agent follows them anyway
- Too many options without a clear default

## Spending context wisely

Once a skill activates, its full `SKILL.md` body loads alongside conversation history, system context, and other active skills. Every token competes for the agent's attention.

**Add what the agent lacks, omit what it knows.** Focus on project-specific conventions, domain-specific procedures, non-obvious edge cases, and the particular tools to use. Don't explain what a PDF is or how HTTP works.

```markdown
<!-- Too verbose — the agent already knows what PDFs are -->
PDF files contain text and images. To extract text, use pdfplumber...

<!-- Better — jumps to what the agent wouldn't know on its own -->
Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.
```

Ask about each piece of content: "Would the agent get this wrong without this instruction?" If no, cut it.

**Design coherent units.** Skills scoped too narrowly force multiple skills to load for one task; skills scoped too broadly are hard to activate precisely. A skill for querying a database and formatting results is one coherent unit; a skill that also covers database administration is probably too broad.

**Aim for moderate detail.** Overly comprehensive skills hurt — the agent struggles to extract what's relevant and may pursue unproductive paths. Concise, stepwise guidance with a working example outperforms exhaustive documentation.

## Calibrating control

**Give the agent freedom** when multiple approaches are valid. Explaining *why* is more effective than rigid directives — agents make better decisions when they understand the purpose.

**Be prescriptive** when operations are fragile, consistency matters, or a specific sequence must be followed:

```markdown
## Database migration

Run exactly this sequence:

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

Do not modify the command or add additional flags.
```

**Provide defaults, not menus.** When multiple tools could work, pick one and mention alternatives briefly:

```markdown
<!-- Too many options -->
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

<!-- Clear default with escape hatch -->
Use pdfplumber for text extraction. For scanned PDFs requiring OCR,
use pdf2image with pytesseract instead.
```

**Favor procedures over declarations.** Teach the agent *how to approach* a class of problems, not *what to produce* for a specific instance. The approach should generalize even when individual details are specific.

## Effective instruction patterns

### Gotchas sections

The highest-value content in many skills is a list of gotchas — environment-specific facts that defy reasonable assumptions:

```markdown
## Gotchas

- The `users` table uses soft deletes. Queries must include
  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
  and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 even if the database is down.
  Use `/ready` to check full service health.
```

Keep gotchas in `SKILL.md` where the agent reads them before encountering the situation. When an agent makes a mistake you correct, add the correction to the gotchas section.

### Templates for output format

Provide a template when the agent must produce a specific output format. Short templates live inline; longer ones go in `assets/` and are referenced conditionally.

```markdown
## Report structure

Use this template:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with supporting data

## Recommendations
1. Specific actionable recommendation
\`\`\`
```

### Checklists for multi-step workflows

```markdown
## Workflow

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

### Validation loops

```markdown
## Editing workflow

1. Make your edits
2. Run validation: `python scripts/validate.py output/`
3. If validation fails, fix and re-run
4. Only proceed when validation passes
```

### Plan-validate-execute

For batch or destructive operations: create an intermediate plan in a structured format, validate it against a source of truth, then execute:

```markdown
1. Extract form fields → `form_fields.json`
2. Create `field_values.json` mapping each field to its intended value
3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
4. If validation fails, revise and re-validate
5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`
```

### Bundling reusable scripts

If execution traces show the agent independently reinventing the same logic across runs — building charts, parsing a format, validating output — write a tested script once and bundle it in `scripts/`. See the scripts reference.

## Structure large skills with progressive disclosure

Keep `SKILL.md` under 500 lines and 5,000 tokens — the core instructions the agent needs every run. When a skill needs more content, move detail to `references/` and tell the agent *when* to load each file:

```markdown
If the API returns a non-200 status code, read `references/api-errors.md`.
```

"Read `references/api-errors.md` if X" is more useful than a generic "see references/ for details." The agent loads context on demand rather than up front.