agentleFS
Sign inStart free
m00kkm00kk/agent-skills-playbook/skills/create-production-skill/SKILL.md

create-production-skill

Skill0 starsChanged 6 months agoMITView on GitHub

Authors production-grade Agent Skills (SKILL.md) per agentskills.io: frontmatter, progressive disclosure, triggers, and validation. Use when creating a new agent skill, writing SKILL.md, or improving skill discovery in Cursor or Claude Code.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Start with Workflow checklist agents can copy

    line 41
  2. Distinctive:

    Prefer commands and templates over prose

    line 42
  3. Distinctive:

    No dates like "before 2025 use old API"

    line 45

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

Create Production Skill

Directory layout

skill-name/
├── SKILL.md          # Required (<500 lines)
├── references/       # Deep docs, loaded on demand
├── scripts/          # Optional CLIs
└── assets/           # Templates

Folder name must match name in frontmatter (lowercase, hyphens).

Frontmatter template

---
name: skill-name
description: >-
  [WHAT in third person]. Use when [triggers: files, verbs, products user mentions].
---

Description rules (discovery)

  • Third person: "Builds MCP servers…" not "I can build…"
  • Include trigger terms users and search engines use
  • Max ~1024 chars; specific beats broad

Body rules

  1. Start with Workflow checklist agents can copy
  2. Prefer commands and templates over prose
  3. Link references/foo.md for anything >100 lines
  4. One decision per section; default + escape hatch
  5. No dates like "before 2025 use old API"

Progressive disclosure

## Additional resources
- Checklist: [references/checklist.md](references/checklist.md)

Instruct: "Read X only when Y" to save context tokens.

Optional scripts

  • Scripts must be safe, non-interactive, documented argv
  • Agent executes scripts; library code stays in project deps

Validation checklist

- [ ] name matches folder
- [ ] description has WHAT + WHEN + keywords
- [ ] SKILL.md < 500 lines
- [ ] No absolute paths or secrets
- [ ] Test: agent invokes /skill-name on realistic prompt

Anti-patterns

  • Vague name: helper, utils
  • Wiki dump in SKILL.md
  • Conflicting instructions with other installed skills

Install path: .cursor/skills/ (project) or ~/.cursor/skills/ (global).

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.

Check your setup, free