agentleFS
robotostudiorobotostudio/turbo-start-web-agent/.claude/skills/write-a-skill/SKILL.md

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

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.
  • victorgarciaesgiSkill

    zoom-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

  • GoogleSkill

    to-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

  • kennethkeimSkill

    ubiquitous-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

  • GoogleSkill

    to-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-hubSkill

    prd-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

  • semtexfromuaSkill

    how-to

    Курс typing-уроків по існуючому проекту — «як написати його з нуля»: аналіз → план у .practicum/course.md → покрокова генерація уроків. Використовуй для команди /vibe-typing:how-to.

    Also in 3 projects that use this

  • +2 more from google

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
  1. Distinctive:

    Ask what the rule is *about*, not who asked for it.

    line 25
  2. Distinctive:

    When it is genuinely both, write the project half here and keep the personal half wherever you keep it.

    line 36
  3. Very specific:

    Check it does not exist: Read the description line of every .agents/skills/*/SKILL.md.

    line 41
  4. Distinctive:

    The description is the only part always loaded: Every other line is read on demand, after something matches.

    line 62
  5. Distinctive:

    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 …

    line 102

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Check it does not exist. Read the description line 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.
  2. Create .agents/skills/<kebab-case-name>/SKILL.md. The directory name is kebab-case; the file is SKILL.md, capitalised exactly that way. One skill per directory.
  3. 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.

  4. 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.
  5. 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, and pnpm run checks fails on the drift — harness:check compares byte for byte.
  6. 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 load AGENTS.md and 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.

  7. Run pnpm run checks, then deliver it the way sync-changes describes: 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.