Agent Engineering

A skill is a directory with a SKILL.md file: YAML frontmatter (required name and description) followed by Markdown instructions. Optional folders hold scripts, references, and assets. The format is an open specification (agentskills.io) used by Claude Code, Cursor, Codex, Copilot, OpenClaw, and others.

release-notes/
├── SKILL.md          # frontmatter + instructions (keep < ~500 lines)
├── references/
│   └── style.md      # read only when needed
├── scripts/
│   └── collect.sh    # executed, not pasted into context
└── assets/
    └── template.md

1. Metadata (~100 tokens): name + description of every skill loaded at startup
2. Instructions (< ~5,000 tokens recommended): the SKILL.md body, loaded when the skill activates
3. Resources (as needed): scripts, references, and assets read or executed only when the task needs them

This is why you can install dozens of skills without drowning the context — until activation, each costs roughly one sentence. It is also why a vague description is fatal: if the model cannot tell when to use a skill, it never loads the body.

• Third person, because descriptions are injected into the system prompt
• Include WHAT and WHEN, plus the words users actually say
• One responsibility per skill — two skills that overlap will fight over activation
• If a skill should only run on request, disable model invocation (supported in Claude Code, Cursor, OpenClaw)

Because the format is shared, a well-written skill ports across tools with little or no change. Tool-specific extras (subagent execution, invocation control, dynamic context injection in Claude Code; gating in OpenClaw) are layered on top of the standard.

A skill is a software artifact that changes agent behavior. Treat it like code: single responsibility, reviewed changes, and behavioral tests instead of vibes.

• Golden tasks: 5–10 representative prompts with expected outcomes; rerun after every skill change
• Measure activation (did it trigger when it should, stay quiet when it should not) and outcome quality
• Read every script in a third-party skill before installing — it runs with your permissions
• Pin versions and prefer registries with scans and provenance (e.g. ClawHub trust envelopes, curated marketplaces)
• Keep secrets out of SKILL.md; inject via environment or tool config

A team wrote a migrations skill. Nobody's agent ever used it.

---
name: db
description: Database helpers.
---
(300 lines of prose mixing migrations, seeding, and backups)

prompt: "add a nullable column to users" → skill not activated
agent writes a blocking ALTER TABLE on a 40M-row table

---
name: zero-downtime-migrations
description: Write and review Postgres migrations with zero-downtime
  patterns. Use when adding columns, indexes, or constraints in
  db/migrations, or when the user mentions a schema change.
---
1. Run scripts/lint-migration.sh on every new migration.
2. Add columns nullable first; backfill in batches; then constrain.
3. Create indexes CONCURRENTLY. See references/patterns.md.

prompt: "add a nullable column to users" → skill activates
golden tasks: 5/5 trigger, 2/2 unrelated prompts stay quiet

• Split one vague skill into focused ones with routing-quality descriptions
• Moved deterministic checks into a script instead of prose
• Measured activation with golden prompts, including negatives