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