Agent Skills Creator

# Authoring Tips

Practical guidance for writing high-signal skill content. These complement the format rules in `format-specification.md`.

## Contents

- Don't State the Obvious
- Build a Gotchas Section
- Use the File System for Progressive Disclosure
- Degrees of Freedom
- Common Content Patterns
- The Description Field Is For the Model
- Think Through the Setup
- Memory and Storing Data
- Store Scripts and Generate Code
- On-Demand Hooks
- Composing Skills
- Measuring Skills

## Don't State the Obvious

Claude knows a lot about coding and your codebase. Focus on information that pushes Claude out of its normal way of thinking.

- If Claude would do it correctly without the instruction, omit it
- General coding advice ("use descriptive variable names") adds noise
- Standard framework conventions (2-space indentation, semicolons) are already known
- Focus on where your org deviates from defaults or where Claude consistently gets it wrong

**Test:** For each line in SKILL.md, ask "Would removing this cause Claude to make a mistake?" If not, cut it.

## Build a Gotchas Section

The highest-signal content in any skill. Build from common failure points Claude runs into when using the skill.

- Place near the end of SKILL.md as a quick-reference section (call it "Gotchas" or "Anti-patterns")
- Ground every gotcha in a real observed failure, not hypothetical concerns
- Update the section over time as new failure modes appear
- Format as short, scannable bullets — not paragraphs

**Good:** "Don't use the brand domain for tenant subdomains — reputation damage from one tenant affects all"
**Bad:** "Be careful with domain naming" (too vague, no reason given)

## Use the File System for Progressive Disclosure

A skill is a folder, not just a markdown file. Think of the entire file system as context engineering. Tell Claude what files are in your skill, and it will read them at appropriate times.

- `references/` — deep-dive documentation loaded on demand
- `scripts/` — executable utilities Claude can compose
- `assets/` — template files for output Claude should copy and adapt (e.g., if your skill produces a markdown report, include the template in `assets/`)
- `examples/` — usage examples and code snippets Claude can reference
- `rules/` — categorized rule files for audit/lint skills

The simplest form of progressive disclosure is pointing to other markdown files. Split detailed function signatures, API docs, or usage examples into separate files and tell Claude when to load them.

## Degrees of Freedom

Match specificity to how fragile the task is. Over-constraining open-ended tasks makes the skill brittle; under-constraining fragile tasks loses determinism.

Analogy: Claude is a robot crossing a landscape. On a narrow bridge with cliffs on either side, hand it exact steps. In an open field, point in a direction and let it choose the path.

**High freedom** — multiple valid approaches; context determines best path. Use prose instructions:

```markdown
Review the code for bugs, readability, and adherence to project conventions.
```

**Medium freedom** — a preferred pattern exists but variation is acceptable. Use pseudocode or parameterized scripts:

```python
def generate_report(data, format="markdown", include_charts=True):
    ...
```

**Low freedom** — fragile, consistency-critical, or destructive. Use specific commands with few parameters:

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

When to be prescriptive: format contracts, safety constraints, naming conventions, API schemas, migrations. When to be flexible: implementation approach, code structure, tool selection.

**Railroading anti-pattern:** "Use exactly this signature: `async function fetchUser(id: string): Promise<User>`"
**Flexible alternative:** "Fetch functions return typed promises and accept string IDs"

## Common Content Patterns

Three patterns recur across skills. Name them explicitly when reaching for one.

### Template pattern

Provide a fixed or flex