agentleFS
afaraha8403afaraha8403/balakit/.cursor/skills/authoring-skills-and-rules/SKILL.md

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.

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
  1. Distinctive:

    Procedure or workflow → Skill: If it has steps, checkpoints, or scripts.

    line 73
  2. Distinctive:

    One capability per Skill: If the description needs "and" to cover unrelated jobs, split it.

    line 78
  3. Distinctive:

    Heuristic: if the workflow is cheap and the user benefits from the agent auto-detecting the need → BOTH.

    line 94
  4. Distinctive:

    Write it in the third person, stating what it does + when to use it.

    line 132
  5. Very specific:

    Prefer Apply when / Use for plus a sibling pointer so the agent does not pick the wrong specialist (use blinded-eval for blinded proof.

    line 133
  6. Very specific:

    Put depth in references/*.md (zero token cost until the agent reads them) and executable logic in scripts/ (run, not loaded into context).

    line 151
  7. Distinctive:

    Place them once as a banner, then echo them where the corresponding behavior is required.

    line 172
  8. Distinctive:

    When a Skill asks a real choice:

    line 221
  9. Very specific:

    Use the host's structured question tool (Cursor AskQuestion, Claude Code AskUserQuestion, OpenCode equivalent).

    line 223
  10. Distinctive:

    Do not replace the checkpoint report with the question.

    line 225
  11. Distinctive:

    Run the checklist below. Any miss → back to the relevant phase.

    line 286
  12. Very specific:

    If the draft changes agent behavior (new workflow, new trigger, new guardrail — not a typo), run blinded-eval before promoting.

    line 288

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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
LoadsOn demand — only when the task matches its descriptionStanding — 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 forMulti-step procedures, reusable workflows, domain playbooksProject facts, coding standards, guardrails, style
AnalogyA specialist you call inHouse rules pinned to the wall
Portable asOne folder, near-identical across 4 of 5 platformsFormat 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.md into 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 combinationWhat the agent seesWhat the user doesWhen to pick
user-invocable: true + disable-model-invocation: false (BOTH)Description in context — agent may auto-invokeMay also /command invokeCommon, safe workflows where auto-detect is desired (this skill)
user-invocable: true + disable-model-invocation: true (USER-ONLY)Description hidden from agentMust /command invoke explicitlyHeavy pipelines the user must opt into (e.g. deep-deliberation) — minimizes context load + unpredictability
user-invocable: false (MODEL-ONLY, rare)Description in contextCannot invoke manuallyAlmost 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, no anthropic/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 in scripts/ (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 slice instead of "don't code layer by layer; seek feedback early".
  • ✅ ground truth instead 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 the name in 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 Code AskUserQuestion, 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 always Say 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: grep the name: 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)

  • name matches the folder name; lowercase-hyphen; no reserved words.
  • description is 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; Copilot applyTo).
  • 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

FileUse it for
references/claude-code.mdClaude Code: SKILL.md fields, .claude/ paths, CLAUDE.md, slash commands
references/cursor.mdCursor: .mdc frontmatter, the 4 activation modes, .cursor/ layout
references/opencode.mdOpenCode: AGENTS.md, opencode.json, agents/commands/skills dirs
references/codex.mdCodex: AGENTS.md hierarchy, config.toml, .agents/skills, prompts (deprecated)
references/copilot.mdCopilot: copilot-instructions, *.instructions.md (applyTo), prompt files
references/cross-platform.mdWrite-once-run-everywhere: the mirror/symlink strategy + AGENTS.md convergence

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.