Claude Skills

A library of Claude Code agent skills, intended to ultimately be packaged and distributed as a Claude Code plugin.

@VOICE.md

Layout

• skills/<skill-name>/SKILL.md — one directory per skill; SKILL.md is the required entry point. skills/ is the distributable set — the plugin root where marketplace installs discover skills. This repo dogfoods them live through a generated symlink farm: .claude/skills/ is a real directory holding one symlink per skills/* entry (skills, shared docs, and contracts/, so each skill's ../GITHUB.md-style links resolve), regenerated by bin/relink-dev-skills.sh. A repo-local skill that must not ship — currently release — lives as a real directory directly under .claude/skills/, outside skills/, so it loads in dev but stays out of the distributable (ADR 0005).
• commands/<name>.md — the collapsed pure commands (ADR 0008): thin in-session wrappers over the bin/<name> adapter binary, holding no mechanics and naming only that binary. A command is the entry point for deterministic work and human-decision-only work (ADR 0008 buckets 1 and 2) — distinct from skills/, which is reserved for agent-native synthesis (bucket 3). commands/ is part of the distributable; bin/relink-dev-skills.sh mirrors it into .claude/commands/ (a second symlink farm alongside .claude/skills/) so the wrappers load live in dev — the one relink now covers both farms.
• Optional per-skill files: REFERENCE.md, EXAMPLES.md, scripts/.
• skills/HANDOVER.md — the per-hop handover contract skills use to chain (and that auto walks). The skill graph lives here: trace a chain by following each skill's default hop. Start from the README I want to… table to find a chain's head.
• skills/DELEGATION.md — the shared rule for keeping the working window bounded by pushing interior work into subagents; referenced by the skills with heavy interiors (auto, pickup, the audits).
• skills/CONCURRENCY.md — how concurrent sessions coordinate without colliding (the two-class model: natural compare-and-swap where no human watches the contended write, an advisory assignee claim where one does); referenced by the skills that select or claim work, with the GitHub bindings in skills/GITHUB.md.
• skills/AUDIT-METHOD.md — the shared method behind the audit-* skills (static-first stance, the map-risk → map-current-state → fan-out-and-score → emit-finding process, the fan-out threshold, the handover row); each audit SKILL.md references it and adds its own risk lens, dimension, and sub-dimensions.
• skills/REVIEW-AID.md — the convention for what a bot PR carries to assist a human's approve decision: a review-aid coverage summary in the PR body (per-acceptance-criterion coverage, residual risk, gate disposition), with a degraded no-brief form; referenced by the two skills that open a bot PR for review (pickup full, patch degraded).
• VOICE.md — how to talk to the user in chat (imported above, always on). WRITING.md — how to write durable prose artifacts (commits, comments, issues, ADRs, docs); referenced by the skills that produce each. ISOLATION.md — how work is kept off your live checkout (read-only repo-root checkout, always a worktree, branch naming, teardown); referenced by the work-producing skills. SECURITY.md — the untrusted-external-content boundary (data-not-instructions, no shell interpolation); injected into context every turn by the always-on hooks/security-boundary.sh UserPromptSubmit hook, with the command-level mechanics in skills/GITHUB.md.

When you add a skill, update README.md and docs/skills-reference.md in the same change: add it to the Skills list, update the I want to… table if it heads or joins a workflow chain (a new row, or an edit to an existing one), and add its entry to the skills reference (the full per-skill blurb — what it does, when to reach for it, an example, and its handover hop) — then rerun bin/relink-dev-skills.sh so the new skill is symlinked into the .claude/skills/ dogfood farm.

Commits

Use Conventional Commits: <type>[scope]: <description>. Types: feat fix chore docs refactor test (same vocabulary as the branch kinds in ISOLATION.md). Subject in imperative mood, lower-case, no trailing period; breaking changes get a ! before the colon or a BREAKING CHANGE: footer. Write the message body per WRITING.md.

Pull requests

Open PRs as the configured bot account, never as the maintainer — identity comes from GITHUB_BOT_ACCOUNT / GITHUB_BOT_TOKEN_CMD (this repo: krixon-bot); command and rationale in skills/GITHUB.md → "PR identity".

Releases

Cut versioned releases with the repo-local release command (/release): it derives the bump from the Conventional-Commit types landed since the last v* tag, bumps .claude-plugin/plugin.json, pushes the bump plus an annotated v<new> tag to main from a worktree, then offers to publish a GitHub release. Human-invoked only — it makes a version judgment and pushes to main, neither safe unattended. land offers it after a merge by discovering this section.

release is a repo-local command (ADR 0008): bumping this plugin's version is specific to this repo, so it never ships to plugin consumers (ADR 0005). The wrapper lives at .claude/commands/release.md — a real, tracked file directly under the .claude/commands/ farm, outside the distributable commands/, the command analogue of how the repo-local skill kept its directory under .claude/skills/. Its mechanics live in the repo-local version binary (.claude/skills/release/scripts/version: derive / apply / publish), which relink-dev-skills.sh leaves untouched. That .claude/-direct home is where any future repo-local command or skill lives, outside the distributable trees.

Goal

• Build out a collection of skills, then package them as a distributable Claude Code plugin (intended to add a plugin.json/marketplace manifest as the library matures).

Agent skills

Issue tracker

Issues and PRs live in GitHub krixon/skills. Skills express the workflow in tracker-neutral concepts; skills/GITHUB.md is the single file that names GitHub — the concepts, commands, and literal label list. Before you type gh in a SKILL.md, stop — that command belongs in skills/GITHUB.md; the skill names the concept and links there. The literal invocation lives in one file, and everywhere else points to it. (Point-of-action form of the rule: it fires at the token where the violation happens, not as a principle to recall.)

Domain docs

Skills ground in whatever documentation a project already has, discovered through the in-context project CLAUDE.md — they impose no layout, taxonomy, or methodology. They use the project's established vocabulary, respect its recorded decisions, and surface conflicts; with nothing documented, they proceed silently. The one artifact a skill persists to the repo is an ADR, offered sparingly on the three-criteria gate and following the project's lead. This repo records its own decisions under docs/adr/.