aitk-claude

name	aitk-claude
description	Claude Code plugin and tooling. Use for adding or modifying plugin skills, the `CLAUDE.md` seed, `aitk claude` commands, or `.claude/context/claude.md`.

Claude

Read .claude/context/claude.md for plugin setup, skills inventory, and aitk claude CLI before editing.

Editing rules

• When updating an internal skill, write to {base-dir}/SKILL.md where {base-dir} is the path shown in the skill header at load time.
• Read .claude/context/claude.md before adding a skill. It lists all existing skills.
• Follow .claude/standards/skill.md for skill structure and frontmatter conventions.
• Audit skill bodies against both .claude/standards/skill.md and .claude/standards/prose.md. The first covers structure and frontmatter. The second covers the body.

Authoring conventions

• Task skills with preview+execute patterns must execute commands immediately after the preview. Do not add a "confirm before running" step or pause for user input. Claude Code's tool permission dialog is the confirmation gate. The user hits Enter to approve or Escape to interrupt and revise.
• When a skill persists output to .claude/ (plans, review, audits), derive a slug from the current git branch: run git branch --show-current and replace / with -. Fall back to latest on empty output (detached HEAD). Include the slug in the filename (feature-<slug>.md, review-<slug>.md, ui-checklist-<slug>.md, ux-audit-<slug>.md). This prevents collisions across parallel worktrees.
• Plugin skills under claude/skills/ do not use the aitk-* prefix. That prefix is reserved for internal skills under .claude/skills/. If a plan suggests aitk-* for a plugin skill, flag the mismatch before creating the folder.
• When handing off a plugin skill test from a linked worktree, print the two-line invocation block: cd to the sandbox path, then claude --plugin-dir <worktree-root>/claude --model sonnet. Without --plugin-dir, Claude loads main's stale copy. Default to --model sonnet for skill testing.
• For unconditional pre-push or per-edit automation (formatters, audits, scaffold checks), propose a husky hook instead of a CLAUDE.md or skill bullet. CLAUDE.md only fires when Claude is acting. A hook fires for everyone.
• When extending PostToolUse hooks (standards-audit and similar), ship only unambiguous regex bans. Defer wordlist or pattern checks to the end-of-cycle claude-standards-audit skill. State the two-layer split when proposing hook scope changes.
• Default cross-project Claude behavior rules (output formatting, path-printing, etc.) to the seeded CLAUDE.md plus the toolkit's own CLAUDE.md. Reserve ~/.claude/ for environment-specific config (terminal capability, machine specifics).

Couplings

Before shipping any change to the seed, a plugin skill, a snippet, or a .claude/ state doc, grep for the identifier you are changing. Check plugin skills for quoted seed section headings, workflows for snippet paths, and .claude/context/claude.md for skill descriptions.

When editing any file under .claude/ in this repo, also check tooling/claude/seeds/ for a mirror path and tooling/claude/reference.md for a description that needs updating.

Sync checklist

When adding a new skill:

• Create the skill folder and SKILL.md in claude/skills/
• Add the skill to the skills table in .claude/context/claude.md
• Draft a scripts/sandbox/<category>/<skill>.sh scenario alongside SKILL.md, even when the skill's output is judgment-driven. The deterministic seeded input is the point. Exception: skills whose body explicitly forbids probing, listing, grepping, or reading project surfaces have nothing for a seeded sandbox to anchor against. Skip the scenario for these and do not list it as a follow-up.
• Claude sandboxes provision fixture state only. The user runs claude from the scenario directory and invokes the skill manually. "Sandbox cannot drive Claude" is not a reason to skip one, because driving is not its job.
• Do not create a matching Gemini command unless explicitly requested. Parity only applies when an existing counterpart changes.

When modifying a skill:

• Update the skills table in .claude/context/claude.md if the description changed
• Check if a corresponding gemini command exists in gemini/commands/ and update it to match
• Check if a corresponding sandbox scenario exists in scripts/sandbox/ and update it if the skill's behavior changed
• Run /aitk-sandbox-check before shipping to audit which skills changed without a paired scenario edit

When modifying the CLAUDE.md seed:

• Check the root CLAUDE.md for drift. Rules that govern both target projects and the toolkit itself should stay mirrored.
• The seed's "Context" section defines the three-tier context model (always-loaded / path-scoped lazy / on-demand lookup at .claude/context/). Keep the section coherent with the same model in .claude/context/claude.md.

When modifying the root CLAUDE.md:

• Check tooling/claude/seeds/CLAUDE.md for a mirror. Project-agnostic rules like behavior, scope discipline, worktree gotchas, and scratch structure belong in both. Toolkit-specific rules like the domain skill table, wiki policy, and tool-agnosticism stay at root only.

Reference

• .claude/context/claude.md: plugin setup, skills inventory, aitk claude CLI
• .claude/context/snippets.md: snippets catalog and invocation
• .claude/context/indexes.md: index.md system rationale and contracts
• tooling/claude/reference.md: seed layout and design notes
• .claude/standards/skill.md: skill structure, frontmatter, and authoring rules