write-a-skill
Skill4 starsChanged 47 days agoMITView on GitHub
Use when asked to remember a rule, save a convention, "make a skill" of something, or write down how this project does a thing — and when you notice yourself being corrected the same way twice. Writes the rule into this repository so every agent on every platform inherits it, instead of into the platform's own memory where only one person gets it.
126 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- annahickman-maker/solo-ostheir own version, first seen Nov 15, 2026
- ceilidhboy/skillstheir own version, first seen Nov 15, 2026
- ydavidtimothy-spec/skillstheir own version, first seen Nov 15, 2026
- RichardDow/skillstheir own version, first seen Nov 15, 2026
- robotostudio/hotrodedited, first seen Nov 8, 2026
- aditya-vermax/skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use zoom-out, to-issues and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
victorgarciaesgiSkillzoom-out
Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
Also in 48 projects that use this
GoogleSkillto-issues
Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.
Also in 43 projects that use this
kennethkeimSkillubiquitous-language
Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
Also in 20 projects that use this
GoogleSkillto-prd
Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
Also in 42 projects that use this
HK-hubSkillprd-to-plan
Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in ./plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets".
Also in 7 projects that use this
semtexfromuaSkillhow-to
Курс typing-уроків по існуючому проекту — «як написати його з нуля»: аналіз → план у .practicum/course.md → покрокова генерація уроків. Використовуй для команди /vibe-typing:how-to.
Also in 3 projects that use this
- +2 more from google
Other versions126 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- robotostudio/hotrod★ 130% same
Wrote their own version · 125
- sanity-io/sanity★ 6.4ksame name
- victorgarciaesgi/regle★ 508same name
- amazingloft999-droid/mattpocock-skills★ 422same name
- InditexTech/weavejs★ 266same name
- ayoubben18/ab-method★ 193same name
- yamcodes/arkenv★ 151same name
- alex-on-ai/WebReaper★ 149same name
- aurorasoft2/Matt_Pocock_Skills★ 133same name
- better-stack-ai/better-stack★ 79same name
- VisualxIntelligence/mattpocok-skills★ 55same name
115 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
- write-a-skillSkill
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 122 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Ask what the rule is *about*, not who asked for it.
- Distinctive: line 36
When it is genuinely both, write the project half here and keep the personal half wherever you keep it.
- Very specific: line 41
Check it does not exist: Read the description line of every .agents/skills/*/SKILL.md.
- Distinctive: line 62
The description is the only part always loaded: Every other line is read on demand, after something matches.
- Distinctive: line 102
If a skill grows past a page or two, it is usually two skills, or one skill with reference material that belongs in a sibling file the …
“Common” is measured: kept by at least 6 in 10 of the 122 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Write it into the repo, not into your memory
Agent platforms offer somewhere private to keep a rule: v0 saves skills to a personal or team workspace, other tools have memory files or account-level custom instructions. Those are the wrong place for anything about this project.
A rule kept in one platform's memory belongs to one person on one platform. The next teammate does not have it. A client editing through their own account does not have it. Codex and Claude Code never see it. Someone who clones this template gets none of it. Six months on, the site's copy is consistent only in the pull requests of whoever happened to save the rule.
A rule kept in .agents/skills/ ships with the repository. Every agent that
works here reads it, it survives the person who wrote it, and changing it is a
pull request someone can review and argue with.
Which one is this?
Ask what the rule is about, not who asked for it.
The repo — anything about this site, its content, its conventions, its tooling: copy style, tone of voice, naming, which Block to reach for, a deployment quirk, a mistake worth not repeating. If a different agent doing the same task should follow it, it goes here.
Your platform's memory — how one person likes to be talked to, their shortcuts, their preferences across every project they touch. If it would make no sense to someone else working on this repo, it does not belong in it.
When it is genuinely both, write the project half here and keep the personal half wherever you keep it.
Writing one
- Check it does not exist. Read the
descriptionline of every.agents/skills/*/SKILL.md. Extending an existing skill beats a second one that overlaps it — two skills covering the same ground means agents follow whichever they happen to load. - Create
.agents/skills/<kebab-case-name>/SKILL.md. The directory name is kebab-case; the file isSKILL.md, capitalised exactly that way. One skill per directory. Open with frontmatter, as the literal first bytes of the file. No comment, no blank line, no generated-file header above it — the agentskills.io spec parses the opening
---and Claude Code fails on anything before it:--- name: <same as the directory name> description: Use when <the situations that should trigger this>. Use whenever <the phrasings someone would actually type>. ---The description is the only part always loaded. Every other line is read on demand, after something matches. So write it as trigger conditions in the words a person would use, not as a summary of the contents. "Use when writing or editing copy for this site" finds the skill; "Copy guidelines" does not.
- Write the rule, and the reason for it. A rule with its reasoning attached survives contact with a case its author did not foresee; a bare instruction gets followed literally into absurdity or dropped as arbitrary. Where a real incident produced the rule, name it and date it — the war story is what makes it stick.
- Run
pnpm harness. This is not optional and nothing will remind you..agents/skills/is mirrored into.claude/skills/by the harness generator, because Claude Code cloud sessions read.claude/and never look at.agents/. A new skill that skips this step is invisible to Claude Code, andpnpm run checksfails on the drift —harness:checkcompares byte for byte. Add a row to the skills table in
AGENTS.md§2, and correct the count in the sentence above it. Nothing enforces this, and skipping it is the quietest way to write a skill nobody reads: Codex, Cursor, Copilot and most of the ecosystem loadAGENTS.mdand never look at.agents/skills/at all, so that row is the only pointer they get. This step was missing from this skill until 2026-08-27, when a skill written by following it landed invisible to Codex and left the count saying six.Describe when to reach for it, in the same voice as the rows already there — the table is read by someone deciding which file to open.
- Run
pnpm run checks, then deliver it the waysync-changesdescribes: a branch and a pull request, never a push to the live branch. The rule lands for everyone when it merges.
Keep it short
A skill is read by an agent mid-task with a job already in hand. Every paragraph competes with the work. Cut anything that is background rather than instruction, and anything the reader could work out from the repo itself.
If a skill grows past a page or two, it is usually two skills, or one skill with reference material that belongs in a sibling file the skill points to.
Skills from elsewhere
This is for skills you write. A skill from a URL, a package, or another repo
is a different decision entirely — it is instructions an agent will follow,
which makes installing one a trust call rather than a copy-paste. See
find-skills before adding any of those.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

