skill-conventions — Claude Code rule: what it does, how to install
skill-conventions defines standards for workflow skills: separates human invocation from auto-triggers, governs state writes, and keeps the skill router in sync.
MIT ★ 2,966 updated 2026-09-29
.cursor/rules/skill-conventions.mdcWhat skill-conventions does
This rule enforces design standards for agent skills. Every skill must declare its intent: either human-run via user-invocable: true for deliberate side-effect rituals, or auto-triggered based on a tight prompt description. If you cannot explain in one sentence when an action should fire on its own, it must stay human-run.
State changes are restricted to three explicit modes: content-addressed add with upsert, targeted update by identified key, and sequential append for trails or handoff logs. A skill that duplicates its own output upon re-running is treated as broken.
Skills move through three states: draft, promoted, and deprecated. Promoting a skill requires registering it in skills/skill-router/SKILL.md and running the deslop skill-file check to ensure instructions stay under one screen without duplicate lines.
What it helps with
- Stop agent skills from auto-triggering on unrelated user prompts
- Prevent duplicated entries when a skill runs more than once
- Classify skills into deliberate human rituals versus automated actions
- Keep the repository skill router synchronized during updates
Example prompts for the agent
- Audit this new skill against skill-conventions before promoting it
- Refine this skill description so the agent triggers it only for database migrations
- Choose the right write semantics for this session-handoff skill
How to install skill-conventions
Manually: put the files in place
.cursor/rules/skill-conventions.mdcFrontmatter: description, globs, alwaysApply
1Plugin marketplace
/plugin marketplace add rohitg00/pro-workflow/plugin install pro-workflow@pro-workflow2Manually: put the files in place
.claude/rules/skill-conventions.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/skill-conventions.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/skill-conventions.mdManually: put the files in place
.clinerules/skill-conventions.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about skill-conventions
How to install skill-conventions in Claude Code?
Register the catalog with /plugin marketplace add rohitg00/pro-workflow, then install it by running /plugin install pro-workflow@pro-workflow. Alternatively, place the rule file directly at .claude/rules/skill-conventions.md.
What does skill-conventions do?
It guides skill authoring by enforcing trigger modes, safe duplicate-free write semantics, and documentation updates across the router index.
When should a skill use user-invocable: true?
Use this flag whenever an action produces side effects, acts as a deliberate session ritual, or lacks a single sentence describing exactly when it should run automatically.
Source text
skill-conventions.mdc · MIT
--- description: Conventions every pro-workflow skill follows - invocation intent, write semantics, buckets, and sync. A skill that gets these wrong misfires, duplicates state, or hides from the people who need it. globs: alwaysApply: true --- # Skill Conventions ## Invocation intent - declare one Every skill is either human-run or auto-triggered. Getting this wrong is the most common failure: a deliberate skill that auto-fires interrupts, an auto-skill with a vague description never fires. - **Human-run** - deliberate, side-effectful, or a session ritual. Set `user-invocable: true`. The user reaches for it on purpose; it should not fire from a stray phrase. Examples: `wrap-up`, `safe-mode`, `agent-teams`, `plan-interrogate`, `auto-setup`, `tdd`, `domain-modeling`. - **Auto-triggered** - the agent should reach for it from the prompt. No `user-invocable` flag; instead the description must be precise enough to fire on the right task and stay silent otherwise. A description that is vague under-fires; one that over-claims interrupts. Examples: `deslop`, `module-map`, `replay-learnings`, `bug-capture`, `wiki-query`. Pick the mode from what the skill does, not from habit. If you cannot say in one sentence when it should fire on its own, it is human-run. The full per-skill classification lives in [`skills/skill-router/SKILL.md`](../skills/skill-router/SKILL.md). ## Write semantics - add vs update vs append A skill that changes stored state (learnings, wiki pages, handoffs, issues) must be explicit about which operation it performs, and must be safe to run twice. - **add** - create a new record. Derive its identity from content, not a fresh random id, so re-running the same input does not duplicate. If a record with that identity exists, reinforce or update it instead of adding a twin. - **update** - modify an existing record addressed by its identity. Never blind-overwrite a record you did not locate first. - **append** - add to an ordered log or list (a session handoff, a research trail) where every entry is meant to persist in sequence. Appends accrete; they never replace. Rule of thumb: re-importable or re-derivable input uses content-addressed `add` with upsert. One-off events use `append`. Corrections to an existing fact use `update`. A skill that re-runs and duplicates its own output is broken, not chatty. ## Buckets Keep the promoted set clean. A skill is either shipped or it is not. - **Promoted** - listed in the router, ready to use, carries a clear invocation intent. Only promoted skills appear in `skill-router`. - **Draft** - work in progress, not yet in the router. Do not promote until it has a stable invocation intent and passes `deslop` skill-file mode. - **Deprecated** - superseded; leave a one-line pointer to the replacement and drop it from the router. ## Sync obligations - **Router** - adding, renaming, removing, or re-scoping a promoted skill updates `skills/skill-router/SKILL.md` in the same change. - **Description** - the description is the auto-trigger surface. When behavior changes, re-tune it so it still fires on the right prompt. - **Quality** - run `deslop` skill-file mode before promoting: no stale lines, no bloat past one screen, no dead sentences, no instruction stated twice, a clear anchor concept, and a declared invocation intent.
© Rohit Ghumare · MIT · rohitg00/pro-workflow