Skill Writing

Goal

Produce a usable Skill package: SKILL.md (always) + optional reference files and scripts (when helpful). Optimize for: discoverability, correctness, concision, testability.

Output contract

When triggered, deliver:

1. SKILL.md with valid YAML frontmatter (name, description)
2. If needed: suggested folder layout + filenames + brief contents for each extra file (do NOT bloat SKILL.md)
3. 3+ evaluation prompts to test activation + behavior

Workflow (do in order)

1) Extract requirements

Capture (infer if missing):

• Primary job: what the Skill reliably accomplishes
• Triggers: phrases/users requests that should activate it
• Inputs: files/types/tools needed (pdf/docx/xlsx/pptx, repos, APIs, etc.)
• Constraints: tone, formatting, compliance, latency, determinism
• Failure modes: common mistakes to guardrail

2) Design information architecture

Use progressive disclosure:

• Keep SKILL.md short (prefer <300 lines)
• Push long content into one-level-deep files:
  • REFERENCE.md (APIs/schemas)
  • WORKFLOWS.md (multi-step procedures)
  • EXAMPLES.md (I/O pairs)
  • CHECKLISTS.md (validation rubrics)
• Prefer scripts for deterministic transforms/validation; document how to run them.

3) Write frontmatter (strict)

• name: lowercase letters/numbers/hyphens only; <=64 chars; no reserved words
• description: 3rd-person; states what + when to use; <=1024 chars; non-empty

4) Write SKILL.md body (minimum necessary)

Include only what improves success:

• Goal
• When to use / When not to use
• Default approach (1 best path)
• Decision points (few, explicit)
• Templates (copy/pasteable)
• Validation loop (draft → check → fix → finalize)
• Examples (at least 2)

5) Add evaluations

Create at least 3 tests:

• Activation test (should trigger)
• Non-activation test (should not trigger)
• Edge case (most likely failure mode)

Templates

Frontmatter template

---
name: <lowercase-hyphen-name>
description: <does X. Use when Y.>
---

SKILL.md skeleton (recommended)

# <Skill Title>

## Goal
...

## When to use
- ...
## When not to use
- ...

## Inputs
- ...
## Outputs
- ...

## Default workflow
1) ...
2) ...
3) ...

## Validation checklist
- [ ] ...
- [ ] ...

## Examples
### Example 1
Input: ...
Output: ...

“High-level + references” pattern

In SKILL.md, link (one level deep):

• REFERENCE.md for details
• WORKFLOWS.md for complex steps
• EXAMPLES.md for many examples Avoid SKILL.md → advanced.md → details.md chains.

Writing rules (hard)

• One primary approach; alternatives only as fallback
• No time-sensitive branching (“before/after date”); instead: “Current method” + “Legacy (deprecated)” section
• Consistent terminology (pick one term per concept)
• No Windows paths; use forward slashes
• If scripts exist: specify exact commands + expected outputs
• Always include a validator/checklist step for fragile tasks

Common anti-patterns

• Vague description (“helps with documents”)
• Too many options (“use A/B/C/D…”)
• Long tutorials Claude already knows
• Deeply nested references
• “Just figure it out” steps without verification

Evaluation pack (copy/paste)

Write 3+ prompts like:

1. “Create a Skill that … (include triggers + constraints). Return SKILL.md.”
2. “User asks for adjacent task that should NOT trigger; respond normally.”
3. “Edge case: missing inputs or conflicting constraints; infer defaults and still produce SKILL.md.”

Done criteria

• Frontmatter validates
• SKILL.md under 500 lines
• Clear activation triggers in description + “When to use”
• Includes checklist + examples + evaluations