Write a skill

Writing Skills

Skills live in skills/<name>/ within this repo and are available as harness:<name> once installed. In Claude Code, run /reload-skills to pick up a new one mid-session; for Codex, run bash update.sh to symlink it into ~/.codex/skills/.

Process

1. Gather requirements - ask user about:

   • What task/domain does the skill cover?
   • What specific use cases should it handle?
   • Does it need executable scripts or just instructions?
   • Any reference materials to include?

2. Draft the skill - create:

   • skills/<name>/SKILL.md with concise instructions
   • Additional reference files if content exceeds 500 lines
   • Utility scripts if deterministic operations needed

3. Review with user - present draft and ask:

   • Does this cover your use cases?
   • Anything missing or unclear?
   • Should any section be more/less detailed?

Skill Structure

skills/skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md Template

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

Description Requirements

The description is the only thing your agent sees when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.

Goal: Give your agent just enough info to know:

1. What capability this skill provides
2. When/why to trigger it (specific keywords, contexts, file types)

Format:

• Max 1024 chars
• Write in third person
• First sentence: what it does
• Second sentence: "Use when [specific triggers]"

Good example:

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

Bad example:

Helps with documents.

When to Add Scripts

Add utility scripts when:

• Operation is deterministic (validation, formatting)
• Same code would be generated repeatedly
• Errors need explicit handling

Scripts save tokens and improve reliability vs generated code.

When to Split Files

Split into separate files when:

• SKILL.md outgrows the core workflow (~120 lines) — move templates, long examples, and reference detail to REFERENCE.md
• Content has distinct domains
• Advanced features are rarely needed

Harness Conventions

Workflow vs. standalone — decide before drafting:

• Workflow skill: fits in the ideate → ship chain. End with a recommended next step (e.g. "Run /qa to verify."). The user invokes it at a specific phase.
• Standalone skill: callable at any time, independent of phase (e.g. /improve-codebase-architecture, /task). Don't recommend a "next step" — just report what was done.

Harness doc paths — if the skill reads or writes project state, use these standard locations:

• .harness/product/CONTEXT.md — domain vocabulary; use exact terms in all output and generated code
• .harness/product/ — product.md, roadmap.md, ux.md, competitors.md
• .harness/engineering/ — architecture.md, implementation-plan.md, features/
• .harness/adr/ — architectural decision records
• .harness/qa/report.md — QA output

Subagents — when spawning subagents, pass file paths, not file contents. Subagents have full repo access. Only pass content directly for small, critical excerpts (e.g. the full text of a feature spec the agent must implement).

Cross-skill references — link to other skills' docs with relative paths (e.g. ../dev-plan/REFERENCE.md).

Review Checklist

After drafting, verify:

• Description includes triggers ("Use when...")
• SKILL.md holds the workflow; templates, long examples, and reference detail live in REFERENCE.md
• Workflow vs. standalone positioning is clear
• Harness doc paths used where relevant
• No time-sensitive info
• Consistent terminology
• Concrete examples included
• References one level deep