mohitagw15856
05b6d799f0
Three more learnings from alirezarezvani/claude-skills, applied: 1. SkillCheck validator (scripts/skillcheck.mjs) — validates every SKILL.md against the authoring standard (frontmatter, name/folder match, trigger + produces clauses, required headings) plus tier referential integrity. Errors fail CI; --strict fails on warnings too. New skillcheck.yml workflow and a SkillCheck status badge in the README. Current: 0 errors / 14 advisory warnings across 172 skills. 2. Cursor export platform — build-exports.mjs now generates exports/cursor/<bundle>/<skill>/<skill>.mdc rule files. The PLATFORMS registry now supports per-skill filenames (file as a function). 3. Per-agent installers — scripts/install.sh unifies install for claude/hermes/codex/openclaw/cursor (--link, --target, --dry-run, --list). Curl-able one-liners codex-install.sh, openclaw-install.sh, and cursor-install.sh clone the library and install in a single command. README documents the one-line installs and Cursor exports; CHANGELOG and the authoring standard updated. Claude-Session: https://claude.ai/code/session_016JWn5jRD5tcEFKrubjQ6Px Co-authored-by: Claude <noreply@anthropic.com>
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# Skill Authoring Standard
|
|
|
|
This is the canonical structure every skill in this library follows. It exists so
|
|
that 160+ skills feel like one coherent product rather than a folder of loose prompts,
|
|
and so contributors know exactly what "done" looks like. If you are adding or editing a
|
|
skill, match this standard.
|
|
|
|
It complements [CONTRIBUTING.md](CONTRIBUTING.md) (how to submit) — this document is
|
|
about *what a good skill contains*.
|
|
|
|
---
|
|
|
|
## 1. File layout
|
|
|
|
```
|
|
skills/
|
|
your-skill-name/
|
|
SKILL.md # required — the skill itself
|
|
scripts/ # optional — stdlib-only helper programs
|
|
your_helper.py
|
|
```
|
|
|
|
- One skill per folder. Folder name = skill name = `name` in the frontmatter.
|
|
- Use lowercase, hyphenated names (`customer-journey-map`, not `CustomerJourneyMap`).
|
|
- A skill must be useful with `SKILL.md` alone. Scripts are an enhancement, never a
|
|
prerequisite.
|
|
- **Never hand-edit `exports/`.** Those platform files (e.g. ChatGPT `SYSTEM_PROMPT.md`)
|
|
are generated from the `SKILL.md` body by `scripts/build-exports.mjs`. Edit the source
|
|
skill and regenerate; CI fails if they drift.
|
|
|
|
## 2. Frontmatter (required)
|
|
|
|
```yaml
|
|
---
|
|
name: your-skill-name
|
|
description: "One sentence on what it does. Use when [trigger conditions]. Produces [the concrete output]."
|
|
---
|
|
```
|
|
|
|
The `description` is the single most important line — it is all the model sees when
|
|
deciding whether to load the skill. It must contain three things:
|
|
|
|
1. **What** the skill does, in one clause.
|
|
2. **Use when…** — explicit trigger phrases a user would actually say.
|
|
3. **Produces…** — the concrete artifact, so the model knows the payoff.
|
|
|
|
Keep it under ~3 sentences. Write triggers from the user's vocabulary, not internal jargon.
|
|
|
|
## 3. Body sections
|
|
|
|
Use this section order. Not every skill needs every section, but strong skills include
|
|
most of them, and the **bold** ones are required.
|
|
|
|
| Section | Purpose |
|
|
|---|---|
|
|
| `# Skill Title` + one-line summary | **Required.** Restate the value in plain language. |
|
|
| **What This Skill Produces** | Bullet list of the deliverables. Sets expectations. |
|
|
| **Required Inputs** | What to ask the user for if it isn't provided. Prevents guessing. |
|
|
| Framework / Formula / Scale | The method, rubric, weights, or formula the skill applies. |
|
|
| Programmatic Helper | If the skill has a script, show how to run it and what it returns. |
|
|
| **Output Format** | A concrete template (headings, tables) of the final artifact. |
|
|
| **Quality Checks** | A checklist the output must pass before it's handed over. |
|
|
| **Anti-Patterns** | Explicit "Do not…" rules — the mistakes this skill prevents. |
|
|
|
|
## 4. Quality bar
|
|
|
|
A skill is ready to merge when:
|
|
|
|
- [ ] The `description` has all three parts (what / use when / produces).
|
|
- [ ] It solves a **recurring** professional workflow, not a one-off task.
|
|
- [ ] It asks for missing inputs rather than inventing them.
|
|
- [ ] The output format is concrete enough that two runs look like the same product.
|
|
- [ ] It includes **Quality Checks** and **Anti-Patterns** — these are what make a skill
|
|
trustworthy, not just a prompt.
|
|
- [ ] It works with no setup beyond reading the file (scripts excepted, and those are
|
|
stdlib-only).
|
|
- [ ] It passes **SkillCheck**: `node scripts/skillcheck.mjs` reports no errors (warnings
|
|
are advisory). CI runs this on every PR that touches `skills/`.
|
|
|
|
## 5. Helper scripts (optional)
|
|
|
|
Some skills ship a `scripts/` folder that computes part of the work. Rules:
|
|
|
|
- **Standard library only.** No `pip install`. No third-party imports.
|
|
- **No network access, no surprise file writes.** Read input, print output.
|
|
- Accept input via flags *and* JSON (file or stdin); offer `--json` output for chaining.
|
|
- Include a module docstring with runnable examples and a `--help` via `argparse`.
|
|
- The script augments the skill — the SKILL.md must still produce a good result without it.
|
|
|
|
See `skills/rice-prioritisation/scripts/rice_calculator.py` for a reference example.
|
|
|
|
## 6. Tone and safety
|
|
|
|
- Write instructions *to the model* ("Ask for…", "Flag any…", "Never write…").
|
|
- British or American spelling is fine; be consistent within a skill.
|
|
- No prompt injection, no instructions to override model guidelines, no requests to
|
|
collect or transmit user data. See [SECURITY.md](SECURITY.md).
|
|
|
|
## 7. Tiering
|
|
|
|
New skills enter as **Experimental**. Once a skill has a stable output format, quality
|
|
checks, and real-world use, it can be promoted to **Stable** or **Production-Ready** in
|
|
[TIERS.md](TIERS.md). Tiering is honest signposting, not a value judgement on effort.
|