Write Your First Skill

Learn the anatomy, study a reviewed example, generate the file below.

Abstract

A skill is a plain-text method your reader hands to an AI assistant. Writing one is closer to writing a procedure for a sharp new colleague than to prompt tinkering: you define the inputs, the steps, the output contract, and the rules that hold when things get ambiguous. This document teaches the anatomy, shows a reviewed example, lists what reviews reject, and ends with an editor that generates a spec-conformant file.

1.Anatomy of a skill

1. Frontmatter. name in kebab-case, matching the filename. description carries two jobs in one paragraph: what the skill does, and — crucially — when to activate it ("Use when asked to…"). Assistants pick skills by this field; a vague description means a skill that sleeps forever. Version, license, authors close the block.
2. Identity paragraph. Two or three sentences after the title, second person: who the assistant becomes and what it refuses to compromise on. This is voice and standard in one breath: "You write commit messages worthy of the permanent record."
3. Inputs. The numbered list of what the skill needs, with the required ones marked and a rule for gaps (ask and stop, or proceed with labeled assumptions). Ask once — a skill that interrogates in rounds exhausts its user.
4. Method. Numbered steps, each one decidable: an instruction the assistant can follow or verify, with the judgment rules spelled out ("when X exceeds Y, do Z"). Steps that say "be thorough" delegate the hard part back to chance.
5. Output format. The contract: sections, order, lengths where they matter. Two runs of the same skill should produce the same shape — the format section is what makes a skill repeatable instead of improvised.
6. Rules. The invariants that survive every edge case: what gets refused, what gets labeled, what degrades and how. State how the skill behaves when a capability is missing — "mark N.A. with a reason" beats a guessed success.

2.A reviewed example, annotated

---
name: honest-status-report
description: Status reports that declare failures,
  blockers and partial results as visibly as successes.
  Use when asked for a status update, a progress report,
  or an end-of-task summary.
---✓ review — name matches filename; description states the trigger ("Use when…"): the assistant knows when to wake this skill
2. Classify each item, strictly:
   - Done & verified — completed AND checked.
   - Failed / errored — attempted, went wrong.
   - Silently skipped — planned, then untouched.✓ review — each category is decidable: two readers classify the same item the same way
The order is fixed: problems before achievements.✓ review — an output contract, stated as a rule: the shape survives every run

3.What reviews reject

Every submission is read line by line by a maintainer, after the automated checks pass. These are the recurring rejections — write with this list open:

1. REJECTED — Undecidable steps. "Analyze carefully", "be helpful", "use best judgment" with zero criteria. A step earns its place when the assistant can tell whether it followed it.
2. REJECTED — Missing degradation. The method assumes web access, code execution or file tools, and says zero about what happens on an assistant that lacks them. Declare the fallback.
3. REJECTED — Hidden or encoded content. Base64 blobs, zero-width characters, instructions to fetch remote content at runtime. Plain readable markdown is the deal: what the reader sees is what the agent executes.
4. REJECTED — Exfiltration paths. Steps that send user data anywhere. A skill transforms what it is given, in place.
5. REJECTED — Vendor lock phrasing. "Use the WebFetch tool", "call Code Interpreter". Name capabilities ("when live web access is available"), and the skill works on every assistant.
6. REJECTED — Marketing in the method. Superlatives about the skill itself, links to products, self-promotion. The method speaks through its steps.
7. REJECTED — A missing output contract. Ten sharp method steps, and zero words on what the deliverable looks like. The format section is half the value.

4.The editor — generate your file

Fill the sections; the editor assembles a spec-conformant .md. Everything runs in this page — your draft touches zero servers.

5.Submit it

1. Run your skill on a real case first — the sample output tells you where the method is thin.
2. Fork the library, add your file under skills/<category>/<name>.md, open one pull request per skill.
3. Sign every commit with git commit -s. That one flag adds the Signed-off-by line certifying you may release the work under Apache-2.0 — the Developer Certificate of Origin. A required check verifies it, so a PR merges once it is there. Already committed without it? git commit --amend -s --no-edit for the last one, git rebase --signoff main for several, then git push --force-with-lease.
4. The automated checks run, then a maintainer reads it line by line. Credit lands in the file itself.