# Examples — Writing Agent Skills

# Contents

• The description formula, worked
• Complete worked example: a skill sharpened (bad → house style)
• The Sharp Skill Checklist (final gate)
• Trigger-eval examples
• Gotchas

# The description formula, worked

[WHAT it does, one clause with key nouns]. Use when [literal user phrases, file extensions, key terms]. Do not use for [nearest neighboring intent].

✅ "Writes user-facing release notes and changelog entries in the house style — benefit-first, grouped by Added/Improved/Fixed. Use when the user asks to write release notes, a changelog entry, a what's-new section, or a version announcement. Do not use for git commit messages, PR descriptions, or API reference documentation."

❌ "A skill for helping with release-related writing tasks." (no triggers, no boundary, would also under-trigger — nothing matches what users type)

# Complete worked example: a skill sharpened

❌ Before:

---
name: json-helper
description: Helps with JSON.
---

# JSON Helper

This skill helps you work with JSON files. JSON (JavaScript Object
Notation) is a popular data format. You can use many tools to work with
it, such as Python's json module, jq, or JavaScript. Depending on the
situation, choose the best tool and be careful with edge cases.

Failures: vague name; description has no WHAT/WHEN/NOT; explains what JSON is; offers a menu with no default; "be careful" is not a procedure; no workflow, no validation, no output spec.

✅ After (house style):

---
name: processing-json
description: Creates, reads, edits, validates, and queries JSON and JSON
  Lines files. Use when the user asks to fix, format, merge, or query a
  .json or .jsonl file, or mentions invalid JSON. Do not use for YAML or
  TOML config files or for designing APIs.
---

# Processing JSON

## Quick reference
Read/write: stdlib `json` — `json.dump(data, f, indent=2,
ensure_ascii=False)`. Large-file queries: `jq` (must be installed).

## Workflow
1. Parse the input; on failure report the parser's line/column verbatim.
2. Apply the change in Python (never regex-edit JSON).
3. Write atomically (temp file, then rename).
4. Validate: re-parse the written file; if it fails, fix and repeat step 2.

## Edge cases
- Trailing commas/NaN: stdlib rejects them — report, don't "repair" silently.

# The Sharp Skill Checklist (final gate)

Triggering: description has WHAT + "Use when" + "Do not use"; literal user phrases; third person; ≤1024 chars; name gerund-form, lowercase-hyphens. Body: <500 lines; no known-content; one default per decision; numbered workflow ending in validation; output fully specified; concrete examples; edge cases addressed. Resources: references one level deep; TOC over 100 lines; execute-vs-read explicit; scripts handle own errors; dependencies stated. Validation: 3+ test prompts incl. ≥1 negative, run before shipping.

# Trigger-eval examples

For processing-json above:

A negative prompt that triggers means the description keywords are too broad — tighten nouns, add the exclusion by name.

# Gotchas

• Descriptions are a shared budget: in Claude Code all skill listings share a character budget and overflow is dropped silently — a bloated description can knock other skills out of context.
• First person kills discovery ("I can help you…") — the description is injected into a system prompt written in third person.
• Nested references get partially read (head -100); keep every reference file linked directly from SKILL.md.
• Time-sensitive facts ("before v2, do X") rot; move legacy notes into a collapsed "old patterns" block or delete them.
• A skill that documents imagined problems stays unused; run the task without the skill first, and write down only what the agent actually missed — that gap is the skill.