yf-skill-authoring

Conventions for authoring Claude Code skills, agents, and instruction files. Covers directory layout, the inline-vs-scri

Conventions for authoring Claude Code skills, agents, and instruction files. Covers directory layout, the inline-vs-script threshold, modularization, token-efficient writing rules, AND Python helper scripts for skills (uv invocation discipline, PEP 723 inline deps, argument parsers).

At a glance

Category: utility
Invocation: auto (fires from its description conditions when relevant work appears)
Requires tools: uv
Depended on by: yf-optimal-instructions
Source: SKILL.md · README.md

When it fires

creating or editing a skill under `.{claude,agents}/skills/*` (user `~/` or project `/`), scaffolding agents, authoring a skill's `SKILL.md` / agent prompt content, writing/editing a `.py` script under `.{claude,agents}/skills/*` to run via `uv run`, adding PEP 723 inline metadata, or asking how to structure skill helpers and instruction files.

When to skip it

project-root instruction files (CLAUDE.md, AGENTS.md, AGENTS/* NOT inside a skill dir) — those route to yf-optimal-instructions; writing application code outside skills, end-user docs, or notes; planning a skill's design beyond conventions (use the project planning skill); backend-specific protocol surfaces (verbs, invocation, translation tables — use the relevant protocol skill); meta-reviewers that overlay these conventions for a specific protocol (use the protocol-specific authoring skill after applying these conventions). Distinguishing axis: yf-skill-authoring owns skill-dir instruction files; yf-optimal-instructions owns project-root ones.

What this skill covers

Structure. Where skill files live, when to extract a script or module, what the directory layout looks like.
Skill Surface Convention. How skills install companion rules, store config and state, register hooks, and run preflight. Seven elements, adopt as a contract. Full spec in reference/SURFACE_CONVENTION.md.
Token efficiency. What to cut and what to keep so always-loaded context stays tight. This is the single source of truth for the token-efficiency ruleset; optimal-instructions cites it.
Python helpers. uv run discipline, PEP 723 inline deps, argument parsers, runtime-cache rules.
Review pipeline. Three read-only review agents (general, reviewer-tokens, red-team) plus a Python-specific reviewer. The reviewer-tokens agent covers skill-dir instruction files; project-root instruction files (CLAUDE.md, AGENTS.md, AGENTS/*) are the optimal-instructions skill's domain.

What this skill does NOT cover

Application code outside .{claude,agents}/skills/.
End-user documentation or operator-facing notes.
Planning a skill's design beyond conventions — that belongs in the project's planning skill.
Backend-specific protocol surfaces (beads vocabulary, protocol verbs, etc.) — those live in their own skills.
Protocol-specific meta-conventions that overlay these rules — those live in protocol-specific authoring skills, applied after these conventions.
Optimizing project-root instruction files (CLAUDE.md, AGENTS.md, AGENTS/* not under a skill dir) — that is the optimal-instructions skill's domain. The token-efficiency ruleset is shared from here; only the trigger surface differs.

When to read what

Authoring a new skill from scratch → read SKILL start to finish, then reference/SURFACE_CONVENTION.md.
Adding a helper script → SKILL § Python helpers (or sibling-language equivalent).
Writing an agent file inside a multi-agent skill → reference/PIPELINE.md.
Referencing skill-internal files from a script → reference/PORTABILITY.md.
Reviewing an existing skill → see § Review sequence in SKILL.
Trimming a skill-dir instruction file → dispatch the agents/reviewer-tokens.md agent. For a project-root instruction file, use the optimal-instructions skill.

Layout shipped by this skill

.{claude,agents}/skills/skill-authoring/
├── SKILL.md
├── README.md                       # this file
├── agents/
│   ├── reviewer.md                 # general skill review
│   ├── reviewer-tokens.md          # token-efficiency reviewer (skill-dir instruction files)
│   ├── red-team.md                 # adversarial skill check
│   └── reviewer-python.md          # Python helper review
├── reference/
│   ├── SURFACE_CONVENTION.md       # full Skill Surface Convention spec + worked example
│   ├── PORTABILITY.md              # SKILL_DIR resolution + portability checklist
│   ├── PIPELINE.md                 # multi-agent skill conventions
│   └── AGENT_ROLES.md              # canonical agent role vocabulary + factoring test + role table
└── scripts/
    └── manifest_update.py          # shared manifest helper (vendored by adopting skills)

Why the convention exists

Skills accumulate divergent init / config / state / hook patterns the moment more than one of them ships. The Skill Surface Convention picks one shape, documents it, and gives adopting skills a hash-checked manifest so installed rule files don't silently drift from the skill source.

The whole convention is an interdependent contract — implementing only some elements produces drift the preflight audit can't recover from. Adopt all seven or none.