@erclx/aitk 0.8.0

package/claude/skills/cli-script/references/template.md

@@ -0,0 +1,43 @@
+# Functional script template
+
+Copy this skeleton for a non-interactive automation script. Keep only the parts the task needs.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() { printf '%s\n' "$*" >&2; }
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: script.sh [options] <arg>
+  -h, --help   Show this help
+EOF
+}
+
+parse_args() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    -*) die "unknown option: $1" ;;
+    *) break ;;
+    esac
+    shift
+  done
+}
+
+main() {
+  parse_args "$@"
+  log "starting"
+}
+
+main "$@"
+```

package/claude/skills/create-rule/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-rule
+description: Scaffolds a project-specific governance rule into `.claude/rules/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
+---
+
+# Create rule
+
+Author a project-local governance rule. The rule lives in the target project, not the toolkit, so it is never overwritten by `aitk gov sync` (sync skips rules with no toolkit source match).
+
+## Guards
+
+- If no `.claude/` directory exists, stop: `❌ No .claude/ directory found. Run aitk init first.`
+- If the request names no behavior to enforce, stop: `❌ Describe what the rule should enforce and which files it applies to.`
+
+## Step 1: gather intent
+
+Resolve both from the request, and ask only for what is missing. Attach a proposed default derived from the request.
+
+- What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
+- Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
+
+## Step 2: resolve band and subdir
+
+Pick the band from the topic. Each band owns a number range and a subdir under `.claude/rules/`:
+
+- `core/` 000-099: global persona, testing, error handling, planning. Always-on, no `paths:`.
+- `lang/` 100-199: one programming language.
+- `framework/` 200-299: one framework.
+- `lib/` 300-399: one library or tool.
+- `ui/` 400-499: UI copy, accessibility, forms.
+- `claude/` 500-599: `.claude/` authoring surfaces.
+
+## Step 3: pick a free number
+
+Pick the lowest unused number in the band that collides with neither the project nor the toolkit catalog:
+
+- Scan the target's `.claude/rules/<subdir>/` for used prefixes.
+- Run `aitk gov list --json 2>/dev/null` and read the shipped rule numbers in the same range, so a later `aitk gov install` cannot double-book the number.
+- If `aitk` is not on PATH, scan the target only and warn that a future toolkit install could collide.
+
+## Step 4: write the rule
+
+Read `.claude/standards/rule.md` for frontmatter, body shape, and voice before writing the body, or `${CLAUDE_SKILL_DIR}/../../standards/rule.md` when the project does not have it. Do not work the shape from memory.
+
+Write `.claude/rules/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, band, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+
+Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
+
+```markdown
+---
+description: <one line, what the rule enforces and where>
+paths:
+  - '<glob>'
+---
+
+# <Topic> standards
+
+## <Group>
+
+- <imperative rule>
+- <imperative rule>
+```
+
+Title casing is sentence case, with proper nouns keeping their own casing (`# TypeScript standards`). `.claude/standards/rule.md` owns the rest of the body shape.
+
+## After writing
+
+Emit the full path on its own line: `.claude/rules/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads a matching file, and always-on rules every session.

package/claude/skills/create-skill/REQUIREMENT.md

@@ -0,0 +1,30 @@
+---
+name: create-skill
+description: What skill creation is for, the gaps it closes, and why it confirms before writing
+---
+
+# Create skill requirement
+
+## Gap
+
+Without this skill, a new skill lands in the wrong shape and the wrong place. A session writes `SKILL.md` from its own idea of the format, writes malformed frontmatter that Claude Code routes on, and never opens the authoring standard that already answers every question it guessed at.
+
+## Must
+
+- Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
+- Confirm the name and the full body with the user before writing. The name is the routing key and a folder that disagrees with its frontmatter fails silently.
+- Write to the conventional skills path, so discovery finds it without configuration
+
+## Must not
+
+- Auto-trigger. Creation is a deliberate act and a skill invented from an ambiguous request is worse than none.
+- Write before the user has seen the body
+
+## Guards
+
+- The authoring standard is not installed: stop and name the command that installs it
+
+## Out of scope
+
+- Editing an existing skill, which the authoring standard and the skill's own requirement govern
+- Judging whether the skill is warranted. A skill nobody needed is an audit finding, not a creation-time refusal.

package/claude/skills/create-skill/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: create-skill
+description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to create a skill, add a skill, or make a new skill.
+disable-model-invocation: true
+---
+
+# Create skill
+
+Read these files from the project root in parallel:
+
+- `.claude/standards/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
+- `.claude/standards/prose.md`: prose conventions for skill body text
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Guards
+
+- If neither `.claude/standards/skill.md` nor `${CLAUDE_SKILL_DIR}/../../standards/skill.md` is present, stop: `❌ skill.md standard not found. Run aitk standards install first.`
+
+## Steps
+
+1. Draft the full `SKILL.md` from the user's description
+2. Confirm the skill name and full content with the user before writing
+3. Write to `.claude/skills/<name>/SKILL.md`

package/claude/skills/create-snippet/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: create-snippet
+description: Creates a new snippet file in `snippets/` (toolkit repo) or `.claude/snippets/` (target project). Use when asked to create a snippet, add a snippet, or make a new snippet.
+---
+
+# Create snippet
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/snippets.md`: authoring conventions, invocation channels, use patterns
+- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Guards
+
+- If neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
+
+## Steps
+
+1. Resolve the write surface: `snippets/` at the project root if present, the toolkit's own authoring source. Otherwise `.claude/snippets/`, a target project's installed copy.
+2. Confirm the slug and full content with the user before writing
+3. Write the file to `<surface>/<slug>.md`
+
+## After writing
+
+- Root surface (`snippets/`): this is the toolkit's authoring source. Remind the user `bun run check` regenerates the consumed copy under `.claude/snippets/`.
+- `.claude/snippets/` surface: the file is project-local. `aitk snippets sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.

package/claude/skills/create-snippet/references/snippets.md

@@ -0,0 +1,57 @@
+---
+title: Snippet reference
+description: Snippet reference and authoring conventions
+consumers: create-snippet
+---
+
+# Snippet reference
+
+## What a snippet is
+
+A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
+
+## Invocation channels
+
+- Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline
+- Claude Code terminal: prefix the install path with `@` (e.g. `@.claude/snippets/claude/feature`)
+- Snippets install preserving the source folder structure. A snippet at `claude/edit.md` installs as `.claude/snippets/claude/edit.md` and is invoked as `@.claude/snippets/claude/edit`
+
+## Use patterns
+
+- Run-as-is: invoke and send immediately. The snippet is self-contained and needs no extra context.
+- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `claude-feature`, then add the feature name or extra constraints)
+- Invoke-on-history: invoke after a discussion. The snippet uses prior conversation as implicit context with no additional input needed (e.g. invoke `claude-figma` after discussing a design).
+
+## Authoring
+
+- One focused purpose per snippet. If it needs headers or multiple goals, use a system prompt instead.
+- Self-contained. No references to external files or assumed prior context.
+- No user fill-in placeholders. If a value depends on context, the user adds it after invocation.
+- Plain markdown only. No YAML frontmatter, no headers, no nested structure.
+- Filename is the slug: kebab-case, no capitals, no underscores
+
+## Structure
+
+- Lead with a verb. Open with an imperative that states the job immediately.
+- One instruction per sentence. Do not stack multiple actions into one sentence.
+- For sequential steps, use a numbered list with one action per item.
+- When the output has a fixed shape, show it in a fenced code block with a language identifier.
+- Put constraints and exclusions last, not inline with the main instructions.
+
+## Examples
+
+### Correct
+
+```markdown
+I want to implement the following. Scan relevant files and list conflicts. Do not implement. # user adds feature after invocation
+Scan relevant files and list conflicts. Do not implement. # run-as-is, no context needed
+```
+
+### Incorrect
+
+```markdown
+I want to implement: <feature or task name> # redundant fill-in, add context after invocation instead
+See ARCHITECTURE.md before starting. # external dependency, not self-contained
+
+## Overview\n## Steps # headers belong in a system prompt, not a snippet
+```

package/claude/skills/create-standard/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: create-standard
+description: Creates a new standard file in `standards/` (toolkit repo) or `.claude/standards/` (target project). Use when asked to create a standard, add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
+---
+
+# Create standard
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/standard.md`: the meta-standard for a standard's shape, frontmatter, and structure
+- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Guards
+
+- If neither `standards/` nor `.claude/standards/` exists, stop: `❌ No standards/ or .claude/standards/ directory found.`
+
+## Steps
+
+1. Resolve the write surface: `standards/` at the project root if present, the toolkit's own authoring source. Otherwise `.claude/standards/`, a target project's installed copy.
+2. Draft the standard from the user's description, following `standard.md` for frontmatter, headings, and structure
+3. Confirm the slug and full content with the user before writing
+4. Write the file to `<surface>/<slug>.md`
+
+## After writing
+
+Emit the full path on its own line.
+
+- Root surface (`standards/`): this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/standards/` and the `standards/index.md` entry, and to add a row to the standards table in `.claude/context/standards.md`.
+- `.claude/standards/` surface: the file is project-local. `aitk standards sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md`, if it should ship to every project.

package/claude/skills/create-standard/references/standard.md

@@ -0,0 +1,52 @@
+---
+title: Standard reference
+description: Shape and content rules for authoring a standard
+consumers: create-standard
+---
+
+# Standard reference
+
+## Overview
+
+A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. One standard governs one doc type. Split unrelated conventions into separate files.
+
+## Frontmatter
+
+- Start the file with a frontmatter block carrying `title` and `description`.
+- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`).
+- `description`: one line naming what the standard covers. It becomes the index link label on install.
+
+## Structure
+
+- Use sentence case for every heading.
+- Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
+- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
+- Order groups from the most-used rule down to the edge case.
+
+## Rules
+
+- Write rules as imperative bullets: one rule per bullet, one concern per group.
+- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories.
+- Cut any rule that resists a crisp one-line phrasing.
+- Do not pad with filler prose. Every line earns its place as a usable reference entry.
+
+## Success criterion
+
+- State what a conforming artifact achieves, not only what shape it takes. A standard that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
+- Write the criterion as a small set of questions the artifact must answer, or a task a reader must be able to complete from it. Keep it checkable by a person in one sitting.
+- Place it near the top, above the shape rules it governs. The shape rules are the means and the criterion is the test.
+- Say that an artifact failing the criterion is non-conforming even when it satisfies every shape rule. Without that line the criterion reads as advice.
+- Add a criterion to an existing standard when that standard is next exercised, not in a sweep. A criterion written without a failure to point at is the taste-based edit this section exists to prevent, so a standard with no criterion yet is a known gap rather than a violation.
+
+## Changing a standard
+
+- Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
+- Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
+- Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
+
+## Examples
+
+- Include examples only where a rule is non-obvious. A self-evident rule needs none.
+- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry.
+- Keep to two or three entries. Show the pattern, not a catalog.
+- Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.

package/claude/skills/docs-sync/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: docs-sync
+description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync docs" or "update the docs". Do NOT use for changelog updates or `CLAUDE.md` updates.
+---
+
+# Docs sync
+
+Read these files from the project root in parallel:
+
+- `.claude/standards/prose.md`: prose conventions for all generated text
+- `.claude/standards/readme.md`: README structure, required sections, and content rules
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+## Diff baseline
+
+Resolve the base ref once and reuse it in Context and in Guards:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill reports nothing to sync rather than admitting it cannot see the work.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against. This is the ordinary shape on `main`, and on a feature branch before its first commit.
+
+An unusable baseline costs only the committed half. `git diff --cached <base>` degrades to the staged set and `git status --short` still reports the working tree, so both reads stay at this skill's own scope. Say so in the preview with `⚠ Baseline unusable. Synced against the uncommitted set only.` The base ref is the only thing this change touches, and the `--cached` scope stays.
+
+## Context
+
+Run these commands in parallel:
+
+- `git diff --cached <base> -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+- `git diff --cached --name-only <base> 2>/dev/null || echo "NO_FILES"`
+- `git status --short 2>/dev/null || echo "NO_STATUS"`
+
+## Guards
+
+- If `git diff --cached <base>` output is empty and `git status --short` output is empty, stop: `❌ No changes since main. Nothing to sync.` Resolve the base ref first. A guard reading bare local `main` stops the skill on `main` before it reaches the corrected read.
+
+## Discovery
+
+Discover docs dynamically. Do not hardcode paths:
+
+- Glob `README.md` at project root
+- Glob `docs/**/*.md`
+
+Read each discovered file in parallel.
+
+## Analysis
+
+For each discovered doc, classify as one of:
+
+- `stale`: the diff touches something the doc describes
+- `unrelated`: no overlap between diff and doc content
+
+Classify at the section level, not the file level. A doc edited earlier in the session can still be partially stale. For each diff surface, verify the corresponding section is synced.
+
+## Action
+
+Rewrite only the stale sections. Do not touch sections unrelated to the diff. Write the updated file immediately after the preview. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+## Response format
+
+### Preview
+
+**Changes since main:** `<n>` files
+**Docs discovered:** `<list>`
+
+| Doc         | Status    | Action |
+| ----------- | --------- | ------ |
+| README.md   | stale     | update |
+| docs/api.md | unrelated | skip   |
+
+After outputting the preview, write all stale updates immediately.
+
+### Summary
+
+One line per file, using the same relative path format as the preview table (e.g. `README.md`, `docs/api.md`):
+
+```plaintext
+✅ Updated: <relative-path>
+⏭️  Skipped: <relative-path>
+```

package/claude/skills/git-branch/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: git-branch
+description: What branch naming is for, the gaps it closes, and where the family boundary sits
+---
+
+# Git branch requirement
+
+## Gap
+
+Without this skill, a branch name is invented once per session. The type prefix drifts from what the history already carries, the name runs past the width a pull request list renders, and a rename lands on a branch that already exists on the remote, which detaches every open pull request pointing at it.
+
+## Must
+
+- Read the branch format reference before generating, so the type vocabulary and the length limit come from one source
+- Derive the name from the commits ahead of main when the invocation carries no description
+- Resolve whether the branch exists on the remote before proposing a rename, since the hazard is invisible from local state
+- Show the name and its length against the limit before renaming
+- Execute immediately after the preview. The tool permission dialog is the confirmation gate.
+
+## Must not
+
+- Rename `main` or `master`
+- Rename when the current name already conforms. The skill is chained, so a conforming name has to pass through rather than churn the branch.
+- Rename a branch that exists on the remote. Local rename plus force push is not the same operation and it breaks the pull request.
+- Emit anything after the result line
+
+## Guards
+
+- On a protected branch: stop and say the branch is protected
+- Name already conforms: stop with a success marker, not a failure, since a chained caller continues past it
+- No commits and no description: stop and name both missing inputs
+- Branch exists on the remote: stop and route to the surface that preserves the pull request link
+
+## Out of scope
+
+- The commit message, which `git-commit` owns
+- Pushing and opening the pull request, which `git-pr` owns. That skill reads a conforming name as a precondition and refuses without one, so this skill runs first.
+- Splitting a branch whose commits span concerns, which `git-split` owns

package/claude/skills/git-branch/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git-branch
+description: Generates and validates conventional branch names. Use for any branch naming or renaming.
+---
+
+# Git branch
+
+Before generating a branch name, read:
+
+- `${CLAUDE_SKILL_DIR}/references/branch.md`: format, types, length limit, and constraints
+
+Follow it exactly.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git branch --show-current 2>/dev/null || echo "NO_BRANCH"`
+- `git rev-parse --verify "origin/$(git branch --show-current)" 2>/dev/null && echo "EXISTS" || echo "LOCAL_ONLY"`
+- `git log main..HEAD --oneline 2>/dev/null || echo "NO_COMMITS"`
+
+## Guards
+
+- If already on main or master, stop: `❌ Cannot rename a protected branch.`
+- If branch name already follows conventions, stop: `✅ Branch name already follows conventions.`
+- If no commits and no args provided, stop: `❌ No commits or description to derive a branch name from.`
+
+## Response format
+
+### Preview
+
+- **Current:** <current_branch>
+- **Suggested:** <suggested_name>
+- **Length:** <count>/50
+- **Status:** <LOCAL_ONLY | EXISTS on remote>
+- **Analysis:** <brief explanation of type choice>
+
+If EXISTS on remote, warn and stop:
+
+```plaintext
+⚠️ Branch exists on remote. Rename manually via GitHub UI or gh CLI to avoid breaking open PRs.
+```
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final command
+
+Only output if LOCAL_ONLY:
+
+```bash
+git branch -m <current> <suggested>
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Renamed: <current> → <suggested>`
+
+Do not add any other text.

package/claude/skills/git-branch/references/branch.md

@@ -0,0 +1,49 @@
+---
+title: Branch reference
+description: Branch naming format and type conventions
+consumers: git-branch, git-split, git-pr, claude-standards-audit
+---
+
+# Branch reference
+
+## Format
+
+- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
+- Length: 50 characters maximum
+- Casing: kebab-case only, no underscores or camelCase
+- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Capture the core change, not the commit message verbatim
+- For branches with multiple commits, use the unifying concern as the description.
+- Do not duplicate type in description (e.g., `feat/feature-login`)
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Examples
+
+### Correct
+
+```plaintext
+feat/jwt-expiration                    # clear feature scope
+fix/AUTH-123-connection-pool           # includes ticket ID
+refactor/remove-deprecated-endpoints   # clear refactor intent
+```
+
+### Incorrect
+
+```plaintext
+feature/auth_stuff                                        # wrong type + underscore
+feat/feature-add-login                                    # duplicates type in description
+fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
+```

package/claude/skills/git-commit/REQUIREMENT.md

@@ -0,0 +1,33 @@
+---
+name: git-commit
+description: What commit generation is for, the gaps it closes, and where the family boundary sits
+---
+
+# Git commit requirement
+
+## Gap
+
+Without this skill, a commit message takes whatever shape the session settled on. The type and scope drift from the convention the history already follows, the subject runs past the length the log renders, and a lockfile diff floods the context the message is derived from so the message describes the lockfile.
+
+## Must
+
+- Read the commit format reference and the versioning standard before generating, so the type, the scope, and the version discipline come from one source
+- Derive the message from the staged diff, with lockfiles excluded
+- Show the message and its length against the limit before committing, so an over-length subject is visible while it is still cheap to fix
+- Execute immediately after the preview. The tool permission dialog is the confirmation gate, and a second prompt trains the user to skim it.
+
+## Must not
+
+- Stage anything. What is committed has to be what the user chose to stage.
+- Commit when nothing is staged
+- Emit anything after the result line. A commit is a step inside a longer flow and prose here buries the next one.
+
+## Guards
+
+- Nothing staged: stop and name the command that stages
+
+## Out of scope
+
+- Splitting a mixed diff across several commits, which `git-stage` owns
+- Naming the branch, which `git-branch` owns. The family shares its triggers and not its gaps: this one turns on the staged diff, the length limit, and lockfile exclusion, none of which a branch name has.
+- Pushing or opening a pull request, which `git-pr` owns

package/claude/skills/git-commit/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: git-commit
+description: Generates conventional commit messages from staged changes. Use for any git commit.
+---
+
+# Git commit
+
+Before generating a commit message, read:
+
+- `${CLAUDE_SKILL_DIR}/references/commit.md`: format, types, scopes, and constraints
+- `.claude/standards/versioning.md` from the project root: phase label vs semver discipline
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+Follow them exactly.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git diff --cached --name-status 2>/dev/null || echo "NO_STAGED_CHANGES"`
+- `git diff --cached -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+
+## Guards
+
+- If staged files output is `NO_STAGED_CHANGES`, stop and output:
+  `❌ No staged changes. Stage files first with git add before committing.`
+
+## Response format
+
+### Preview
+
+- **Files:** <if ≤3 list all, if >3 show first 3 + "+N more">
+- **Message:** `<type>(<scope>): <subject>`
+- **Length:** <count>/72
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Final command
+
+```bash
+git commit -m "<type>(<scope>): <subject>"
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Committed: <type>(<scope>): <subject>`
+
+Do not add any other text.