--- name: Skill Authoring slug: skill-authoring-3 category: AI Engineering description: Skill Authoring provides principles for writing skills that behave the same way every run. Use it when adding, editing, or reviewing a skill in this plugin. github: "https://github.com/nyldn/claude-octopus/tree/main/skills/skill-authoring" language: Shell stars: 3971 forks: 374 install: "npx degit https://github.com/nyldn/claude-octopus/tree/main/skills/skill-authoring ~/.claude/skills/skill-authoring" installs_to: ~/.claude/skills/skill-authoring source_path: skills/skill-authoring/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/nyldn/claude-octopus" added: 2026-08-16T07:01:32.652Z last_synced: 2026-08-16T07:01:32.652Z canonical_url: "https://dirskills.com/skills/skill-authoring-3" --- # Skill Authoring Skill Authoring provides principles for writing skills that behave the same way every run. Use it when adding, editing, or reviewing a skill in this plugin. **Install:** ```bash npx degit https://github.com/nyldn/claude-octopus/tree/main/skills/skill-authoring ~/.claude/skills/skill-authoring ``` ## README > **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`. # Skill Authoring A skill exists to get determinism out of a stochastic system. **Predictability** is the goal, and it means the agent takes the same *process* every run — not that it produces the same output. Every rule below serves that. `docs/PLUGIN-ASSEMBLY-STANDARD.md` already fixes the *structure* a skill body should take. This is about what makes the content inside that structure work. Adapted from `writing-great-skills` in [mattpocock/skills](https://github.com/mattpocock/skills) (MIT), with the invocation section rewritten for how this plugin actually loads skills. ## When To Use - Writing a new skill, or reviewing one in a PR. - A skill fires when it should not, or fails to fire when it should. - A skill behaves differently run to run on the same input. - Deciding whether something should be a skill at all, or a command, or prose in `CLAUDE.md`. ## When Not To Use - For the mechanical checklist — file layout, registration, required sections. That is `docs/PLUGIN-ASSEMBLY-STANDARD.md` and the CI suites. - For writing prompts that are not skills. That is `skill-meta-prompt`. ## Inputs The skill under construction or review, and an honest answer to: what should the agent do differently because this exists? ## Workflow ### Invocation: explicit by default Every shipped command and skill carries `disable-model-invocation: true`. Claude Code therefore keeps Octopus out of model context until the user chooses an `/octo:*` command. This is a hard platform gate, not a prose reminder. Command bodies that need reusable instructions load the entire source file directly from `${HOME}/.claude-octopus/plugin/.claude/skills//SKILL.md`; they do not call the Skill tool. `${HOME}/.claude-octopus/plugin` is the stable, self-healed path available to model tool calls; `CLAUDE_PLUGIN_ROOT` is a hook/runtime variable and may be absent from that context. The command must treat the loaded body as the active instructions in the current conversation, follow its steps in order, and pass the user's text as workflow arguments rather than executable path content. This keeps explicit commands composable without reopening automatic model invocation. Plain-language routing is a separate, legacy-compatible opt-in controlled by `OCTOPUS_AUTO_ROUTER_MODE=suggest|invoke`. Its default is `off`. New skills must never depend on prompt-keyword auto-routing for reachability. ### Writing the description The description does two jobs: say what the skill is, and list the branches that should trigger it. It sits in the context window every turn, so it earns harder pruning than the body. - Lead with the word that does the invoking. - **One trigger per branch.** Synonyms that rename the same branch are duplication: "use for test-first development … when the user wants TDD" is one branch written twice. - Cut identity that the body already carries. Triggers, plus any "when another skill needs this" clause, and nothing else. - Beware collision. With this many skills the scarce resource is trigger space, not skill count. Before adding a trigger phrase, check whether an existing skill or `hooks/user-prompt-submit.sh` already claims it. The hook is opt-in, but overlapping phrases still degrade routing for users who enable it. ### Information hierarchy Content is either a **step** (an ordered action) or **reference** (a rule or fact consulted on demand). A skill can be all of one, or both. Place each piece on the rung it belongs: 1. **In-skill step** — what the agent does, in order. 2. **In-skill reference** — consulted while working. A flat set of peer rules is a legitimate shape, not a smell. 3. **External reference** — pushed into a sibling file and reached by a pointer, loaded only when the pointer fires. `skills/blocks/` is where shared ones live. Push too little down and the top bloats; push too much and the agent never finds what it needs. Branching is the cleanest test: inline what every run needs, push behind a pointer what only some runs reach. ### Completion criteria Every step ends on a condition that says the work is done. Make it: - **Checkable** — can the agent tell done from not-done without guessing? - **Exhaustive where it matters** — "every changed file accounted for" rather than "review the changes". A vague criterion invites stopping early on something that looks finished. "Produce a summary" is not a completion criterion. "Every boundary in the table maps to a real handoff in the setup" is. ### Enforcement, and its cost A body that names the orchestrator script directly is required by `tests/unit/test-mandatory-compliance.sh` to carry a `MANDATORY COMPLIANCE` block and a `PROHIBITED` list. That is deliberate for skills that dispatch providers and spend money. It is dead weight on an advisory skill — so if a skill only advises, refer to workflows by their `/octo:` command names and skip the ceremony rather than adding a compliance block nobody needs. ## Provider Or Data Priority 1. The existing skills, as worked examples of the conventions. 2. `docs/PLUGIN-ASSEMBLY-STANDARD.md` for required structure. 3. The CI suites, which encode constraints prose does not mention. ## Stop Or Checkpoint Rules - Stop before adding a skill whose triggers overlap an existing one. Extend the existing skill instead; a near-duplicate makes both harder to reach. - Stop if the answer to "what does the agent do differently" is "nothing it would not have done anyway". - If the content is one paragraph of advice with no process, it belongs in the skill that already covers the area, not in a new file. ## Output Contract When reviewing, report: 1. **Verdict** — ship, revise, or fold into an existing skill. 2. **Predictability risks** — where two runs would diverge. 3. **Trigger collisions** — which existing skill or hook arm competes. 4. **Criteria that are not checkable** — quoted, with a replacement. 5. **Misplaced content** — what should move up or down the hierarchy. ## Verification - The description names distinct branches, with no synonym pairs. - Every step has a criterion the agent can evaluate. - No trigger phrase collides with `hooks/user-prompt-submit.sh` or an existing skill's description. - The skill is registered in `.claude-plugin/plugin.json` and `make sync` is clean. - It declares `disable-model-invocation: true`, and any command that composes it loads its source file directly. - `tests/unit/test-explicit-activation.sh` passes.