Skip to content
Skills Library
AI & agents · Building & coding

write-skill

/write-skill

Use when someone asks for a new skill, a slash command or a reusable agent recipe for working on this repo, or to fix a skill that is wrong or out of date. Keeps every skill usable by Claude Code and Codex alike, links it into .agents/skills and lists it in AGENTS.md. Not for the plugin, which ships no skills.

Licence
MIT
Last repository change
28.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when someone asks for a new skill, a slash command or a reusable agent recipe for working on this repo, or to fix a skill that is wrong or out of date. Keeps every skill usable by Claude Code and Codex alike, links it into .agents/skills and lists it in AGENTS.md. Not for the plugin, which ships no skills.

Original author description

Use when someone asks for a new skill, a slash command or a reusable agent recipe for working on this repo, or to fix a skill that is wrong or out of date. Keeps every skill usable by Claude Code and Codex alike, links it into .agents/skills and lists it in AGENTS.md. Not for the plugin, which ships no skills.

How it works

  1. Steps
  2. Done means
  3. Never
  4. Traps
Original SKILL.md headings · 60 lines, 667 words
SKILL.md preview
---
name: write-skill
description: >-
  Use when someone asks for a new skill, a slash command or a reusable agent recipe for working on this repo, or to fix
  a skill that is wrong or out of date. Keeps every skill usable by Claude Code and Codex alike, links it into
  .agents/skills and lists it in AGENTS.md. Not for the plugin, which ships no skills.
---

# Write a skill

Skills here serve the people and agents who work on this repo, in Claude Code and Codex alike; the plugin users
install has none. A skill is a recipe an agent follows: steps in a fixed order, a definition of done, hard nevers, and
the traps already paid for. Deterministic work belongs in a script the skill calls, not in prose the agent has to get
right.

## Steps

1. **Check it is needed.** Search `.claude/skills/` for a skill that already covers the request; change that one
   rather than adding a near-duplicate.
2. **Create the folder** `.claude/skills/<name>/` with `SKILL.md`. The folder name equals `name`: lowercase letters,
   digits and hyphens, at most 64 characters.
3. **Frontmatter** holds `name` and `description`, and nothing else. The description puts the trigger first
   ("Use when ..."), names the requests that should fire it, and stays within 1,024 characters. Write it as a `>-`
   block, as every skill here does: a `: ` or ` #` in a plain value is invalid YAML for the tools that parse it
   strictly.
4. **Body,** at most about 200 lines, in the house shape (`start-work` is the model):
   - what the skill is for, in two or three sentences;
   - **Steps:** numbered, each naming the file, tool or command it touches. A scope (a diff, a review, a branch) is
     named as the git command that resolves it, never in words;
   - **Done means:** what must be true when the agent stops;
   - **Never:** the hard rules;
   - **Traps,** once there are some: what broke, when, the guard.
   A file the skill reads beside `SKILL.md` (such as `lenses.md`) sits in its folder and is named in the step that
   uses it.
5. **Scripts** a skill needs live in `tools/`, Node's standard library only, with tests in `tools/<name>.test.ts`, and
   are named by their path from the repo root (`node tools/<name>.ts`). If the work is deterministic, write the script
   first.
6. **Link it for Codex:** `node tools/setup.ts link <name>`. It writes `.agents/skills/<name>` into git's index as a
   symlink to the skill, so the commit has the link on any machine, a Windows clone without Developer Mode included.
   Commit the link with the skill.
7. **List it** in `AGENTS.md`, in the skills line under How a change lands: its name and when to use it.
8. **Run `node tools/gate.ts quick`.** It checks the frontmatter (only `name` and `description`, the name equal to the
   folder, the description set, "Use when ..." first, within 1,024 characters), that `AGENTS.md` names the skill, and
   that each skill has its link and each link leads to a skill. The rest is review.

## Done means

- The skill fires on the requests in its description and on nothing unrelated.
- Every path, tool and command it names exists.
- `.agents/skills/<name>` links to it, `AGENTS.md` names it, and gate quick passes.

## Never

- Claude-only syntax in a skill: `!` shell injection, `$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_PROJECT_DIR}`,
  or `allowed-tools`.
- A skill that restates a rule instead of pointing at it: name the section of `AGENTS.md` or `REVIEW.md`.
- A rule kept only in a skill's prose when a check could keep it: add the check to `tools/gate.ts`, with its test.
- `ln -s` from Git Bash, or a copied folder, for the link: use `node tools/setup.ts link`.

## Traps

| What broke | When | The guard |
|---|---|---|
| A skill's folder name differed from its `name`, and the tool dropped the skill without a word | another repo, 2026-10 | gate quick compares them |
| Git Bash's `ln -s` copied the folder instead of linking it, and Codex read a stale copy | another repo, 2026-10 | `setup.ts link`; gate quick reads each link's mode from git's index |
| A description with `: ` in it read fine in Claude Code and was invalid YAML in Codex | another repo, 2026-10 | Every description is a `>-` block; gate quick refuses a plain one with `: ` |

Versions

RepositoryScoreLicence
This page · serionist/claude-session-restore90MIT
hassan-mohiddin/freeflow100MIT
jelvodev/yaap100MIT
cao-partners-au/olc-agent-skills-starter100MIT
wilbeibi/claude-toolkit100MIT
NormandErwan/claude-casebook98BSD-3-Clause
hassan-mohiddin/freeflow96MIT
LandonSchropp/agent-toolkit90MIT
pwguler/skills82MIT

Database snapshot: 13.11.2026 · package version 68b4e53fb49e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-skill
    Create a new agent skill (or Claude Code slash command) from a plain-language description, using live spec fetching, pattern research, and an approval-gated blueprint before any files are written. Use whenever the user wants to build, scaffold, or author a new skill, subagent…
  • 100skills-creator
    Create plugin components (skills, agents, commands, full plugins) and decide skill vs agent architecture. TRIGGER WHEN: creating, adding or scaffolding a new skill, agent, command or plugin ("new skill", "new agent", "new plugin", "skills-creator"). DO NOT TRIGGER WHEN: auditing…
  • 100skill-creator
    Create new AI agent skills for Claude Code, Codex, and Cursor. Use when asked to create a skill, add a new agent capability, or set up a slash command.
  • 100new-skill-creator
    Scaffold a new Agent Skill end-to-end into a skills repo you maintain (folder, SKILL.md, optional protocol.yon for dual-doc skills, tri-runtime links for Claude Code + Codex + the shared .agents/ dir, commit and push). The maintainer's authoring loop — it links your own clone…
  • 100create-command
    Create a new slash command for Claude Code. Guides the user through defining the command name, what it does, and generates the markdown file in .claude/commands/. Use when the user says 'create a command', 'new command', 'add a slash command', 'I want a shortcut for', or wants…
  • 100edit-tool
    Creates, modifies, and orchestrates Claude Code tools (skills, agents, scripts). Use when user requests creating, updating, improving, or editing any Claude Code extension — skills, sub-agents, slash commands, script wrappers. Triggers include "create/make/new…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.