From 8a944c9190a9684f3381e2a74f984978eb74b9b3 Mon Sep 17 00:00:00 2001 From: Mohit Date: Tue, 25 Aug 2026 11:15:04 +0100 Subject: [PATCH 1/2] Add Agent Skill Authoring (SKILL.md) rule --- README.md | 1 + rules/agent-skill-authoring.mdc | 121 ++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 rules/agent-skill-authoring.mdc diff --git a/README.md b/README.md index 8204dac5..4cb3f1d7 100644 --- a/README.md +++ b/README.md @@ -314,6 +314,7 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir ### Documentation +- [Agent Skill Authoring (SKILL.md)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/agent-skill-authoring.mdc) - Frontmatter contract, required sections, and the quality bar for writing reusable Agent Skills. - [Gherkin Style Testing](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/gherkin-style-testing-cursorrules-prompt-file.mdc) - Behavior-driven scenarios and acceptance criteria. - [How-To Documentation](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/how-to-documentation-cursorrules-prompt-file.mdc) - Task-oriented guides and procedural documentation. - [README Best Practices](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/readme-best-practices-cursorrules-prompt-file.mdc) - README documentation with best practices integration. diff --git a/rules/agent-skill-authoring.mdc b/rules/agent-skill-authoring.mdc new file mode 100644 index 00000000..f96247b0 --- /dev/null +++ b/rules/agent-skill-authoring.mdc @@ -0,0 +1,121 @@ +--- +description: Author and review Agent Skills (SKILL.md) — frontmatter contract, the three-part description, required sections, and the quality bar that separates a reusable skill from a saved prompt +globs: **/SKILL.md, **/skills/**/*.md, **/.claude/skills/**/*.md, **/.cursor/skills/**/*.md +alwaysApply: false +--- + +# Authoring Agent Skills (`SKILL.md`) + +A skill is a markdown file an agent loads on demand to do one recurring job to a +professional standard. It is not a saved prompt: a prompt is used once by the +person who wrote it, a skill is used repeatedly by people who did not. + +Apply these rules when creating or editing a `SKILL.md`. + +## File layout + +``` +skills/ + your-skill-name/ + SKILL.md # required — the skill itself + references/ # optional — worked examples, deeper method + scripts/ # optional — standard-library-only helpers +``` + +- One skill per folder. Folder name = skill name = frontmatter `name`. +- Lowercase and hyphenated (`customer-journey-map`, never `CustomerJourneyMap`). +- The skill must be useful from `SKILL.md` alone. Scripts are an enhancement, + never a prerequisite. + +## Frontmatter + +```yaml +--- +name: your-skill-name +description: "What it does. Use when . Produces ." +--- +``` + +`description` is the single highest-value line in the file — it is usually all +the model sees when deciding whether to load the skill at all. It must contain +three things: + +1. **What** it does, in one clause. +2. **Use when…** — trigger phrases in the user's vocabulary, not internal jargon. + Write what someone would actually type, including the messy phrasings. +3. **Produces…** — the concrete artifact, so the payoff is legible. + +Keep it under ~700 characters. A description that omits triggers is the most +common reason a good skill never gets loaded. + +## Required sections + +| Section | Purpose | +|---|---| +| `# Title` + one-line summary | Restate the value in plain language. | +| **What This Skill Produces** | The deliverables, as bullets. Sets expectations. | +| **Required Inputs** | What to ask for if not provided. Prevents invention. | +| Framework / Formula | The method, rubric, or weights the skill applies. | +| **Output Format** | A concrete template — headings, tables, fields. | +| **Quality Checks** | A checklist the output must pass before hand-over. | +| **Anti-Patterns** | Explicit "do not" rules — the mistakes this prevents. | + +Quality Checks and Anti-Patterns are what make a skill trustworthy rather than +merely well-formatted. Write the anti-patterns from real failure, not from +imagination: they are the part a practitioner recognises. + +## The quality bar + +- [ ] The description has all three parts (what / use when / produces). +- [ ] It solves a **recurring** job, not a one-off task. +- [ ] It asks for missing inputs instead of inventing them. +- [ ] The output format is concrete enough that two runs look like one product. +- [ ] It works with no setup beyond reading the file. +- [ ] Instructions are written **to the model** ("Ask for…", "Flag any…", + "Never state…"), not to the reader. + +## Helper scripts + +If the skill ships `scripts/`: + +- **Standard library only.** No `pip install`, no third-party imports — the + helper must run on whatever interpreter the user already has. +- **No network access and no surprise file writes.** Read input, print output. +- Accept input via flags *and* JSON; offer `--json` output for chaining. +- Include a module docstring with a runnable example and `--help` via `argparse`. +- If it uses randomness, expose `--seed`. Unreproducible output cannot be verified. + +## Anti-patterns + +- **A saved prompt with a frontmatter block.** If it does not generalise past + your own last task, it is not a skill. +- **A description with no triggers.** The skill never loads, and no amount of + body quality compensates. +- **Inventing inputs.** A skill that guesses the user's numbers produces + confident, wrong artifacts. Ask. +- **Output format as prose.** "Write a summary" gives two different documents on + two runs; a template gives one product. +- **Anti-patterns invented rather than observed.** They are the section + practitioners judge the skill by. +- **Scripts that are required.** The moment `SKILL.md` alone stops working, the + skill has become software with a README. +- **Letting placeholder text ship.** Scaffolded `TODO` and `[bracketed]` text in + a description means the skill was never actually written. + +## Validating + +Structure can be machine-checked before review: + +```bash +npx skillspec-check ./skills # or: npx pm-claude-skills skillcheck +``` + +It reports a missing trigger clause, a name that does not match its folder, +placeholder text left in a description, and absent Quality Checks or +Anti-Patterns sections. + +--- + +*Derived from the [SKILL.md authoring standard](https://github.com/mohitagw15856/pm-claude-skills/blob/main/SKILL-AUTHORING-STANDARD.md) +used across an open-source library of 1,000+ skills, where the rules above are +enforced in CI.* From 7e176f68492dcc1d9ba9e25d38b612e51e024328 Mon Sep 17 00:00:00 2001 From: Mohit Date: Tue, 25 Aug 2026 11:57:01 +0100 Subject: [PATCH 2/2] Scope glob to SKILL.md; mark sections required/optional/conditional --- rules/agent-skill-authoring.mdc | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/rules/agent-skill-authoring.mdc b/rules/agent-skill-authoring.mdc index f96247b0..bb0fd987 100644 --- a/rules/agent-skill-authoring.mdc +++ b/rules/agent-skill-authoring.mdc @@ -1,6 +1,6 @@ --- -description: Author and review Agent Skills (SKILL.md) — frontmatter contract, the three-part description, required sections, and the quality bar that separates a reusable skill from a saved prompt -globs: **/SKILL.md, **/skills/**/*.md, **/.claude/skills/**/*.md, **/.cursor/skills/**/*.md +description: Author and review Agent Skills (SKILL.md) — frontmatter contract, the three-part description, which body sections are required, and the quality bar that separates a reusable skill from a saved prompt +globs: **/SKILL.md alwaysApply: false --- @@ -48,17 +48,21 @@ three things: Keep it under ~700 characters. A description that omits triggers is the most common reason a good skill never gets loaded. -## Required sections - -| Section | Purpose | -|---|---| -| `# Title` + one-line summary | Restate the value in plain language. | -| **What This Skill Produces** | The deliverables, as bullets. Sets expectations. | -| **Required Inputs** | What to ask for if not provided. Prevents invention. | -| Framework / Formula | The method, rubric, or weights the skill applies. | -| **Output Format** | A concrete template — headings, tables, fields. | -| **Quality Checks** | A checklist the output must pass before hand-over. | -| **Anti-Patterns** | Explicit "do not" rules — the mistakes this prevents. | +## Body sections + +| Section | Status | Purpose | +|---|---|---| +| `# Title` + one-line summary | Required | Restate the value in plain language. | +| What This Skill Produces | Required | The deliverables, as bullets. Sets expectations. | +| Required Inputs | Required | What to ask for if not provided. Prevents invention. | +| Framework / Formula / Scale | Optional | The method, rubric, weights, or formula the skill applies. | +| Programmatic Helper | Conditional | Required only if the skill ships a script: how to run it and what it returns. | +| Output Format | Required | A concrete template — headings, tables, fields. | +| Quality Checks | Required | A checklist the output must pass before hand-over. | +| Anti-Patterns | Required | Explicit "do not" rules — the mistakes this prevents. | + +Keep them in this order. Not every skill needs the optional rows, but strong +ones usually carry most of them. Quality Checks and Anti-Patterns are what make a skill trustworthy rather than merely well-formatted. Write the anti-patterns from real failure, not from