author-skill
Use when authoring a NEW rsc skill or editing an existing one — scoping it to one job, writing the description that decides whether it ever loads, splitting the body into references/, writing its evals, auditing it against the rubric. NOT building a product feature (that is `specify`) and NOT designing an agent loop (that is `building-agents`).
ericrisco · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ericrisco/rsc-harness --skill author-skillAbout this skill
name: author-skill
description: "Use when authoring a NEW rsc skill or editing an existing one — scoping it to one job, writing the description that decides whether it ever loads, splitting the body into references/, writing its evals, auditing it against the rubric. NOT building a product feature (that is specify) and NOT designing an agent loop (that is building-agents)."
tags: [skill, authoring, meta]
recommends: []
origin: risco
author-skill — write skills that trigger and teach
This is the meta skill: it authors and edits the other skills in the rsc catalog. A skill is two things bolted together — a description that fires at the right moment, and a body that makes the agent better once it fires. Most skills fail on the first. Treat them as two separate engineering problems with two separate quality bars.
Where the SDD chain (specify → plan → … → ship) builds product, author-skill builds the tools that build product. Use it whenever a skill is born or edited.
Not this skill — delegate: a product feature specced or planned → ../specify/SKILL.md, ../plan/SKILL.md. An autonomous agent or tool-calling loop → ../building-agents/SKILL.md. Generic project docs or a wiki article → the ../harness/SKILL.md 02-DOCS engine. Bootstrapping a workspace or profiling the user → ../init/SKILL.md.
Read 02-DOCS/wiki/harness/user-profile.md and work at the accompaniment dial it records; ../init/SKILL.md owns that dial and sets it. With no profile, default to non-technical framing and ask for the technical level and the dial before going deep — skill authoring is itself a technical act, so many users want more narration here than they do elsewhere.
What a skill is (the anatomy)
skills/<id>/
├── SKILL.md the body: frontmatter (name + description + origin) then the prose
├── references/ progressive-disclosure detail, loaded only when the body points to it
│ └── <topic>.md
├── evals/
│ ├── cases.yaml trigger + capability test cases
│ └── README.md how to run the evals, honestly
└── scripts/ optional; verify.sh + helpers for skills with a checkable artifact
└── verify.sh
The frontmatter decides if the skill loads. The body decides how good the agent is once it does.
The description — the single highest-leverage line
The description sits in context on every turn the skill is installed, invoked or not. The body is only paid for when the skill fires; the description is paid for always. So length here is a cost, never a credit. A vague description is a skill that never fires; an over-broad one hijacks unrelated turns. Get this right before anything else.
Rules, all enforced:
- Third person, present tense. "Use when authoring a new skill…" — never "I help you…" or "You should…". The agent is reading about the skill.
- Discriminative, not exhaustive. Lead with a
Use when …clause naming the situation, then only the capabilities that separate this skill from its neighbours. Do not append aTriggers: '…', '…'phrase list: the model matches on meaning, so a keyword bank in three languages buys nothing and is charged on every turn. The test is discrimination, not coverage — could a reader pick this skill over its nearest sibling from this line alone? - Draw the boundary. End with a
NOT <x> (that is <sibling>)clause, naming a sibling that actually exists underskills/. Negative space prevents hijacking as much as positive matching causes firing. - Aim ≤ 350 characters; 1024 is the schema-enforced hard limit. One physical line, wrapped in double quotes, internal quotes escaped or avoided. If it does not parse, the skill does not load.
origin: riscoon its own line. This marks it as ours.
# Good — situation, the few capabilities that discriminate, a real boundary
description: "Use when X happens or the user shows symptom Y — doing A, fixing B, choosing C. NOT Z (that is `sibling`)."
# Bad — first person, no situation, no boundary; competes with every sibling on every turn
description: "I help you write great skills and make them work."
The full recipe, the budget tactics, and a worked before/after → references/description-recipe.md.
Progressive disclosure — the body is an index, not an encyclopedia
The body is loaded in full whenever the skill fires, so every line competes for the agent's attention. Write the smallest body that still routes correctly: 400 lines is a ceiling, not a target, and there is no floor — a skill that does its job in 60 lines beats the same skill padded to 200. Push anything long, reference-like, or rarely-needed into references/<topic>.md and link it inline at the point of use ("full table → references/foo.md").
Decide where a paragraph lives:
| Put it in the body when… | Move it to references/ when… |
|---|---|
| The agent needs it on every run | It is needed only in a specific branch |
| It is a rule, a gate, or a decision point | It is a long table, a catalog, or a template |
| It is short and load-bearing | It is reference detail that would bloat the body |
| Cutting it would change behavior | It is an example that illustrates but does not instruct |
Every file under references/ must be linked from the body. An unlinked reference is never loaded, so it is dead weight in the package — link it or delete it.
The hybrid structure — when each piece earns its place
- SKILL.md — always. Frontmatter + focused body.
- references/ — only when the body genuinely needs offloaded depth. Do not create an empty
references/to look complete; a single-file skill is fine. - evals/ — always.
cases.yaml+README.md. A skill with no evals is unverifiable and does not ship. - scripts/verify.sh — only when the skill produces a checkable artifact (code, config, copy with a ban-list). Process skills — those judged on the safety rails they