authoring-skills-and-rules
Skill1 starsChanged 11 days agoMITView on GitHub
Author Skills (SKILL.md) and rules/instructions across Claude Code, Cursor, OpenCode, Codex, and GitHub Copilot. Covers frontmatter, file layout, activation, mirroring, and craft: progressive disclosure, Apply-when descriptions, leading words, playbook steps copied into todos, skip reasons, the deletion test, and user-facing questions in plain English. Apply when the user asks to write, scaffold, refactor, port, or review a Skill, Cursor rule (.mdc), AGENTS.md, copilot-instructions, or prompt file — or to make one Skill/rule work across multiple agents. Use blinded-eval when a behavior-changing draft needs blinded proof. Use dissect to audit an existing system, not to author a skill.
In this repository107 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/base.mdcCursor rule
- .cursor/rules/changelog.mdcCursor rule
- .cursor/rules/comments.mdcCursor rule
- .cursor/rules/release.mdcCursor rule
- .cursor/rules/seo-ai-search.mdcCursor rule
- .cursor/rules/testing.mdcCursor rule
- agent-readySkill
- authoring-skills-and-rulesSkill
- blinded-evalSkill
- cloakbrowser-fallbackSkill
- deep-deliberationSkill
- design-rationaleSkill
- dissectSkill
- documentation-writerSkill
- everything-seoSkill
- executeSkill
- generating-app-verifySkill
- inceptionSkill
- kit-workflowsSkill
- marketing-psychologySkill
- media-genSkill
- nlm-skillSkill
- opinionSkill
- proving-change-safetySkill
- refreshing-app-verifySkill
- release-deploySkill
- seo-auditSkill
- startup-marketing-brainSkill
- subsystem-walkthroughSkill
- trlSkill
- unmatched-workflowSkill
- agent-readySkill
- authoring-skills-and-rulesSkill
- blinded-evalSkill
- cloakbrowser-fallbackSkill
- deep-deliberationSkill
- design-rationaleSkill
- dissectSkill
- documentation-writerSkill
- everything-seoSkill
- executeSkill
- generating-app-verifySkill
- inceptionSkill
- kit-workflowsSkill
- marketing-psychologySkill
- media-genSkill
- nlm-skillSkill
- opinionSkill
- proving-change-safetySkill
- refreshing-app-verifySkill
- release-deploySkill
- seo-auditSkill
- startup-marketing-brainSkill
- subsystem-walkthroughSkill
- trlSkill
- unmatched-workflowSkill
- agent-readySkill
- blinded-evalSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 73
Procedure or workflow → Skill: If it has steps, checkpoints, or scripts.
- Distinctive: line 78
One capability per Skill: If the description needs "and" to cover unrelated jobs, split it.
- Distinctive: line 94
Heuristic: if the workflow is cheap and the user benefits from the agent auto-detecting the need → BOTH.
- Distinctive: line 132
Write it in the third person, stating what it does + when to use it.
- Very specific: line 133
Prefer Apply when / Use for plus a sibling pointer so the agent does not pick the wrong specialist (use blinded-eval for blinded proof.
- Very specific: line 151
Put depth in references/*.md (zero token cost until the agent reads them) and executable logic in scripts/ (run, not loaded into context).
- Distinctive: line 172
Place them once as a banner, then echo them where the corresponding behavior is required.
- Distinctive: line 221
When a Skill asks a real choice:
- Very specific: line 223
Use the host's structured question tool (Cursor AskQuestion, Claude Code AskUserQuestion, OpenCode equivalent).
- Distinctive: line 225
Do not replace the checkpoint report with the question.
- Distinctive: line 286
Run the checklist below. Any miss → back to the relevant phase.
- Very specific: line 288
If the draft changes agent behavior (new workflow, new trigger, new guardrail — not a typo), run blinded-eval before promoting.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Authoring Skills and Rules (cross-platform)
Leading words: progressive disclosure, context pointer, token budget, Apply-when description, playbook todos, skip reason, leading words, phase separation, encode lessons in structure, deletion test, plain question.
A practitioner's guide to writing and maintaining the two artifact families that steer coding agents — Skills (on-demand, procedural capabilities) and Rules / instructions (standing context) — across Claude Code, Cursor, OpenCode, Codex, and GitHub Copilot.
Trigger: /authoring-skills-and-rules, or any request to write, port, or
review a Skill or rule. If the target platform(s) are unstated, ask before
scaffolding — the file layout differs per platform.
This skill carries the per-platform exact details in references/ (loaded on
demand). The body below is the decision model + the universal craft + a
phase-separated workflow.
The one decision that comes first: Skill vs Rule
Pick the artifact by how the behavior should load, not by topic.
Skill (SKILL.md) | Rule / instructions | |
| Loads | On demand — only when the task matches its description | Standing — always, or auto-attached by file glob |
| Cost | ~Free until triggered (only the description is always in context) | Taxes every request it applies to |
| Best for | Multi-step procedures, reusable workflows, domain playbooks | Project facts, coding standards, guardrails, style |
| Analogy | A specialist you call in | House rules pinned to the wall |
| Portable as | One folder, near-identical across 4 of 5 platforms | Format differs sharply per platform |
Rules of thumb:
- Procedure or workflow → Skill. If it has steps, checkpoints, or scripts.
- Always-true fact or guardrail → Rule. "We use Vitest", "never commit secrets", "this repo is a monorepo".
- A standing block that grew past a few paragraphs and became procedural →
graduate it from the rule/
CLAUDE.mdinto a Skill. - One capability per Skill. If the description needs "and" to cover unrelated jobs, split it.
User-invoked vs Model-invoked
For Skills, the second decision (after Skill-vs-Rule) is how the Skill is
triggered. The description is the swing vote.
| Flag combination | What the agent sees | What the user does | When to pick |
user-invocable: true + disable-model-invocation: false (BOTH) | Description in context — agent may auto-invoke | May also /command invoke | Common, safe workflows where auto-detect is desired (this skill) |
user-invocable: true + disable-model-invocation: true (USER-ONLY) | Description hidden from agent | Must /command invoke explicitly | Heavy pipelines the user must opt into (e.g. deep-deliberation) — minimizes context load + unpredictability |
user-invocable: false (MODEL-ONLY, rare) | Description in context | Cannot invoke manually | Almost never — restricts user control |
Heuristic: if the workflow is cheap and the user benefits from the agent auto-detecting the need → BOTH. If the workflow is heavy (multiple subagents, human checkpoints, large context budget) → USER-ONLY, so the agent does not fire it on a whim.
Cross-platform support — the leverage point
SKILL.md is now a cross-agent standard. As of Dec 2025, all five — Claude
Code, Cursor, OpenCode, Codex, and Copilot — auto-discover Skills from a
skills/ directory. Author a Skill once and mirror the folder into each agent's
location. What still differs sharply is rules (standing instructions).
Key leverage: .agents/skills/ and .claude/skills/ are shared cross-agent
directories — Codex, OpenCode, and Copilot all read them (and Claude Code
reads .claude/skills/). A single authored folder, mirrored (or symlinked) into
the right places, covers every agent for skills. The remaining per-agent work
is rules.
For the per-platform exact paths, precedence, field semantics, and the mirror strategy this very repo uses, see:
- references/cross-platform.md — write-once-run-everywhere strategy
- references/claude-code.md
- references/cursor.md
- references/opencode.md
- references/codex.md
- references/copilot.md
Universal craft (applies to every platform)
1. The description is the product
On every platform, the description is the only thing always in context — it is what the model reads to decide whether to pull in the Skill or rule. Spend your effort here.
- Write it in the third person, stating what it does + when to use it.
- Prefer Apply when / Use for plus a sibling pointer so the agent
does not pick the wrong specialist (
use blinded-eval for blinded proof; use dissect for an existing-system audit). - Pack in concrete triggers: file types, tool names, verbs, user phrases.
- ✅ "Extract text and tables from PDFs, fill forms, merge documents. Use when the user mentions PDFs, forms, or document extraction."
- ❌ "Helps with documents." / "I can help you with files."
- For an Agent-Requested Cursor rule, the description is the whole trigger — name the framework/domain and the situations that should pull it in.
- Limits: Anthropic Skill
description≤ 1024 chars;name≤ 64 chars, lowercase + digits + hyphens only, noanthropic/claude.
2. Progressive disclosure — keep the entry file lean
Once a Skill/rule loads, every token competes with the conversation. Structure so detail loads only when needed.
- SKILL.md body: keep it well under ~500 lines. Cursor docs say the same for rules: "Keep rules under 500 lines."
- Put depth in
references/*.md(zero token cost until the agent reads them) and executable logic inscripts/(run, not loaded into context). - Reference one level deep only. A reference that links to another reference
may get truncated (the agent previews with
head) and lose context.
<skill-name>/
├── SKILL.md # metadata + decision model + workflow (lean)
├── references/ # per-topic detail, loaded on demand
│ └── <topic>.md
└── scripts/ # executable helpers (optional)3. Leading words — the agent's reasoning anchor
Leading words are dense phrases that pack a lot of meaning into a small space. Put them in the skill body (typically under the title as a banner) and the agent will repeat them in its own reasoning traces, which anchors its behavior to your intent without long prose.
- ✅
vertical sliceinstead of "don't code layer by layer; seek feedback early". - ✅
ground truthinstead of "always read the real artifacts before branching". - Place them once as a banner, then echo them where the corresponding behavior is required. The agent's thinking traces are the audit channel — if it is not echoing the leading word, the steering did not take.
4. Naming and scope
- One capability per Skill. Gerund or plain-descriptive names
(
processing-pdfs,authoring-skills-and-rules) beat vague ones (helper,utils). The Skill folder name must equal thenamein frontmatter (and on OpenCode/Codex, match the directory). - One concept per rule. Split large standards into composable rules rather than one giant file.
5. Write for a smart reader, concretely
- Assume the agent is capable — don't explain
git,npm, or basic concepts. - Be actionable and specific, like a sharp internal doc. Prefer examples and
@file/ path references over pasting whole files. - Tell it to do the thing; skip the reason unless the rule is confusing without one. Justification that does not change a decision is sediment.
- No time-sensitive phrasing ("after August 2025, do X"). Skills are long-lived; describe the current way and collapse legacy into an aside.
- Justify constants (why
timeout=30), and declare dependencies and how to install them — never assume a tool is present.
6. Playbook steps become todos
Numbered workflow steps are copyable. On invoke, open a todo list whose
first items are those steps, copied verbatim. A step you choose not to
do stays in the list with skip: <reason> or n/a: <reason>. Skipped rigor
must stay inspectable. Give the skill a reply contract (what the agent
returns when the workflow ends).
7. Encode lessons in structure
The second time you write the same instruction, encode it as a lint, a
script, a metadata flag, or a test — then delete the prose. Do not grow the
SKILL.md. Optional: a custom subagent_type whose first instruction is "read
this skill in full" prevents generalPurpose drift. Use it when the skill
is a style wrapper; keep generalPurpose when you want model diversity.
8. What to leave out
- Secrets, API keys, tokens — ever.
- Whole style guides (use a linter) and generic tool docs the agent already knows.
- Rare edge cases and duplicated codebase docs (link to the canonical source).
- No-ops — paragraphs that, if deleted, would not change agent behavior. Run the deletion test: if the agent would still do the right thing without it, cut it.
- Sediment — stale instructions left by previous authors. Audit and prune.
9. User-facing questions are for the human
The skill body talks to the agent. Checkpoints talk to the human. A product owner must be able to pick an option without knowing the skill's jargon.
When a Skill asks a real choice:
- Use the host's structured question tool (Cursor
AskQuestion, Claude CodeAskUserQuestion, OpenCode equivalent). Numbered text fallback if missing. - Do not replace the checkpoint report with the question. Report first (plain-terms lead, then detail), then the question, then stop.
- Prompt: one sentence of the choice, in product language. Jargon stays above.
- Labels: short, concrete, first is
(Recommended), last is alwaysSay this in plain English. - That last option is a meta question: do not advance. Rephrase + one example of what each real option means here, then re-ask.
- One question at a time. Free-text always overrides.
Workflow — 4 phases (creating or updating)
Each phase ends with a checkpoint. Do not skip ahead — phase separation prevents the agent from rushing to draft before the scope is locked.
Phase 1 — Scope
- [ ] Classify: Skill vs rule (use the table above)
- [ ] Choose invocation: BOTH vs USER-ONLY (use the decision table above)
- [ ] Confirm target platform(s) — ask if unstated🛑 Checkpoint: State the classification, invocation flag, and platform list
in one sentence. Do not proceed to Draft until the user confirms (or you are
explicitly operating solo and the scope is unambiguous). Ask with the host's
structured question tool. Prompt in plain English. Last option:
Say this in plain English (meta: rephrase + example, do not advance).
Phase 2 — Draft
- [ ] Write the description first (Apply when + sibling pointer), third person
- [ ] Scaffold the correct file layout per platform (see references/)
- [ ] Write the lean body; inject leading words; numbered steps that can be
copied into todos; skip:/n/a: for dropped steps; reply contract
- [ ] Push depth to references/, logic to scripts/Copy this phase's checklist into the todo list verbatim before drafting.
A skipped item stays with skip: <reason>.
🛑 Checkpoint: Read the description aloud. If you cannot name the triggers crisply, the scope is still fuzzy — go back to Phase 1.
Phase 3 — Distribute
- [ ] Mirror/port the source folder to every requested platform
- [ ] For Copilot, translate to .github/instructions/*.instructions.md
(applyTo if path-scoped) or .prompt.md
- [ ] For Skills: copy the folder to each platform's location
(see references/cross-platform.md)🛑 Checkpoint: grep the name: slug across the repo. Every mirror must be
in sync before validating.
Phase 4 — Validate
Run the checklist below. Any miss → back to the relevant phase.
If the draft changes agent behavior (new workflow, new trigger, new
guardrail — not a typo), run blinded-eval before promoting. Hold the
rubric back from the draft's authoring pass. Typos and comment-only edits
skip eval (skip: formatting-only).
Updating an existing Skill or rule
The 4 phases apply, with these additions:
- Phase 1:
grepthename:slug across the repo to locate every copy (source + mirrors under.cursor/,.agents/,.claude/). - Phase 2: Edit the source of truth only; never hand-edit a mirror.
Bump the
version(SemVer) in frontmatter. Re-check the description against the new behavior — stale triggers are the most common rot. - Phase 3: Re-mirror from source so mirrors never drift. Update the changelog/README if the repo tracks them.
- Phase 4: Same checklist.
Validation checklist (before declaring done)
namematches the folder name; lowercase-hyphen; no reserved words.descriptionis third person, ≤1024 chars, and states what + when with concrete triggers.- Invocation flags set intentionally (BOTH vs USER-ONLY) and match the workflow's weight.
- Leading words injected as a banner and echoed where the corresponding behavior is required.
- Entry file is lean (well under 500 lines); depth is in
references/. - References are one level deep; no nested reference chains.
- No secrets; dependencies declared; constants justified.
- Correct frontmatter for the platform (e.g. Cursor
globs/alwaysApply; CopilotapplyTo). - If multi-platform: every requested platform has its copy/translation, and mirrors are in sync.
- One capability per Skill / one concept per rule.
- Deletion test run on every paragraph — no no-ops, no sediment.
- Numbered steps are copyable into todos; skipped steps have
skip:/n/a:; a reply contract exists. - Behavior-changing drafts ran blinded-eval, or an explicit
skip:for formatting-only. - User-facing questions (if any) are plain questions: host structured
question tool, product-language prompt, last option
Say this in plain English.
References
| File | Use it for |
| references/claude-code.md | Claude Code: SKILL.md fields, .claude/ paths, CLAUDE.md, slash commands |
| references/cursor.md | Cursor: .mdc frontmatter, the 4 activation modes, .cursor/ layout |
| references/opencode.md | OpenCode: AGENTS.md, opencode.json, agents/commands/skills dirs |
| references/codex.md | Codex: AGENTS.md hierarchy, config.toml, .agents/skills, prompts (deprecated) |
| references/copilot.md | Copilot: copilot-instructions, *.instructions.md (applyTo), prompt files |
| references/cross-platform.md | Write-once-run-everywhere: the mirror/symlink strategy + AGENTS.md convergence |
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
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.

