Index of every page on this site: llms.txt
All skills
Run it yourself

Writes and refines agent skills (a SKILL.md plus optional reference files and scripts) in one standard shape - a trigger-first description, a body under 100 lines, detail split one level deep, and a quick with/without test. Use when the user wants to create a skill, turn a workflow, habit or repeated correction into a skill, edit or tighten an existing SKILL.md, or fix a skill that does not trigger. Not for running formal benchmarks or description-optimization loops - use skill-creator.

  • 3 files
  • 8.7 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/avik-creator/agent-skills/writing-skills

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈127 tokens for metadata: the name and description. ≈1.3k when used: this file. ≈758 more on demand in 2 files.

Description uses 6.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈508 characters, or 6.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Writing Skills

A skill works only if its description makes the agent load it at the right moment, and its body then changes what the agent does. Every rule below serves one of those two.

Quick start

  1. Copy TEMPLATE.md to <skill-name>/SKILL.md.
  2. Write the description first.
  3. Fill the body and stop at 100 lines.
  4. Test with 2-3 real prompts, then run the checklist.

Workflow

1. Capture intent

  • Editing an existing skill: read its struggles/ notes first (see Struggle notes below).
  • Mine the conversation, memory and past corrections before asking anything; a correction the user repeated is the strongest rule you have.
  • Ask only what is left: what it does, when it triggers, what the output looks like, what it is not for.
  • Restate the intent and get a yes before drafting; a wrong restatement is cheap, a wrong skill is not.

2. Pick the right home

  • Skill: a workflow started on demand (write a PR, review a diff).
  • CLAUDE.md: a rule that must hold every session (comment style); a skill may never load for it.
  • Hook: a rule that must never break (no auto-commit); instructions can be ignored, hooks cannot.

3. Write the description

The agent sees only name + description when choosing; the body is invisible until then.

  • name: lowercase, hyphens, max 64 chars, matches the folder.
  • Third person, max 1024 chars.
  • Sentence 1: what it does, concretely.
  • Sentence 2: Use when ... with the phrases and contexts users really type, including asks that never name the skill; agents undertrigger, so lean broad.
  • Sentence 3 (if a neighbour exists): Not for X - use Y.
  • All "when to use" lives here, never in the body.

Good: Extract text and tables from PDFs, fill forms, merge files. Use when working with PDFs or the user mentions forms or document extraction. Bad: Helps with documents. (nothing to tell it apart from any other skill)

4. Write the body

  • Imperative voice, with a one-line why beside each rule; the agent generalises from reasons but follows a bare MUST literally.
  • Concrete examples (input -> output, before -> after) beat abstract advice.
  • One term per concept, used everywhere.
  • Nothing time-sensitive (versions, prices, "currently"); if unavoidable, put it in a reference file someone updates.
  • Write for every future prompt, not just the examples you drafted with.
  • Delete any line the agent would follow anyway; it only costs context.
  • Nothing that would surprise the user if read aloud.
  • Plain English: state the claim directly (not "it's not X, it's Y"), cut clauses the sentence doesn't need, and add no number, source or stake the facts don't have.

5. Split when it grows

  • Body past 100 lines, distinct domains, or rarely needed detail -> move it to a reference file.
  • Link each file from SKILL.md with when to read it: See [references/go.md](references/go.md) when the code is Go.
  • References stay one level deep; a file over 300 lines gets a table of contents.
  • One domain per file, so the agent reads only the one it needs.

6. Add scripts only when earned

Add scripts/ when a step is deterministic (validate, format), when every test run rewrote the same helper, or when errors need exact handling. Scripts run without entering context, so they save tokens and drift.

7. Test

Follow EVALS.md: cases with must and must-not written first, three arms, quoted grades.

  • Write 2-3 prompts a real user would type: casual, specific, with paths and context.
  • Run each with and without the skill (one subagent each, same turn) and compare with the user.
  • Read the transcripts, not just the outputs; cut any section that sent the agent down a wasted path.
  • Try 2-3 near-miss prompts that share keywords but should not load the skill.
  • Fix a failure by sharpening the reason, not by adding a MUST for that one case; rerun until the user is happy.

Struggle notes

When a skill goes wrong in real use (it didn't load, loaded for the wrong request, a rule misled the agent, a case was missing, or two rules conflicted), tell the user in one line what happened and why. Then add <skill>/struggles/<YYYY-MM-DD>-<slug>.md with:

  • the request, what the skill made the agent do, and what should have happened
  • why it went wrong, with the transcript line or output as evidence
  • the change to the skill you would propose

Git ignores struggles/, because the notes come from real projects. Change the skill only after a yes, as a normal generic edit, then add "Fixed in <commit or PR>" to the note.

Review checklist

  • Description: third person, what + Use when ..., max 1024 chars
  • Neighbour skill named with Not for ... - use ... where one exists
  • SKILL.md under 100 lines
  • References one level deep, each linked with when to read it; every link resolves and every file under references/ is linked
  • Every rule has a one-line why; no caps-lock MUSTs
  • At least one concrete example
  • Consistent terms, nothing time-sensitive
  • Tested with and without the skill, including near misses
  • A Replies line tells the agent to talk to the user in simple English
  • Every line earns its place

Replies

Talk to the user in simple English: short sentences, everyday words, and a technical term only where it is needed, explained the first time it appears.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at a0324a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 3 weeks ago

README badge

README badge for avik-creator/agent-skills/writing-skills