# Skill Authoring

Principles for writing skills that behave the same way every run, use when adding...

- Repository: https://github.com/nyldn/claude-octopus (4351 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nyldn/claude-octopus --skill skill-authoring -g -a claude-code -y`
Codex: `npx skills add nyldn/claude-octopus --skill skill-authoring -g -a codex -y`
Cursor: `npx skills add nyldn/claude-octopus --skill skill-authoring -g -a cursor -y`
Gemini CLI: `npx skills add nyldn/claude-octopus --skill skill-authoring -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add nyldn/claude-octopus`

## Description

Principles for writing skills that behave the same way every run, use when adding, editing, or reviewing a skill in this plugin

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Skill Authoring

Load `skills/blocks/engineering-method-selection.md` from the installed plugin
and apply only the methods relevant to this task. Preserve this entry point's
execution contract and output format. Read referenced skills as instructions;
do not invoke the current command recursively or add provider calls from a seat.

## Domain language

Load `skills/blocks/domain-modeling.md` when a skill discusses providers, models,
access, billing, reviewers, or votes. Reuse the shared definitions instead of
inventing local synonyms. State the source and time of observations. Never infer
authentication, entitlement, billing mode, quota, or model-family independence
from a binary or transport name alone.

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

The rest: https://github.com/nyldn/claude-octopus/blob/HEAD/.claude/skills/skill-authoring/SKILL.md