mtk-agent-toolkit: Skill for Claude Code

Instructions

Overview

Two modes over the project constitution, both append-only and approval-gated: audit re-grades what is there against the codebase and fixes rot; capture adds what this session learned that the constitution was missing.

When To Use

• audit: every 4–8 weeks, after a large refactor, or when sessions hit broken commands or dead paths ("AGENTS.md feels off").
• capture: at the end of a session that discovered a command, gotcha, env quirk or non-obvious pattern ("save what we learned", "remember this for next time").

When NOT To Use

• First-time setup → /mtk-setup. Refreshing architecture-principles.md → /mtk-setup --audit.
• An engineer correction → lessons capture (a lesson, not a constitution fact). Session state to resume → handoff.
• Audit right after a clean audit, or capture mid-task — both manufacture churn.

Workflow

Both modes

• Resolve the target first. The constitution is AGENTS.md when it exists, carries no Auto-generated by MTK marker in its first 10 lines, and CLAUDE.md is absent or a shim (a bare @AGENTS.md line); otherwise CLAUDE.md (legacy repo). bash scripts/resolve-constitution.sh answers the same question. No constitution → stop and point to /mtk-setup. Never migrate legacy → inverted as a side effect; that is /mtk-setup's regen-diff job.
• Both files are protected (S1.5): Edit with explicit old/new strings, never Write, even when the engineer asks for a rewrite.

Audit mode

1. Mechanical currency checks — run, do not eyeball.

   CONST="$(bash scripts/resolve-constitution.sh)"
   bash scripts/verify-references.sh "$CONST" .claude/rules/*.md   # exit 3 = STALE lines
   bash scripts/check-instruction-load.sh   # exit 1 = a file a harness truncates, shadows or ignores; 2/missing = report "not checked"
   

   Extract the constitution's build/test/lint/format commands as name<TAB>command lines and run them through bash scripts/verify-commands.sh --timeout 120. Never pass deploy, migrate, publish, push or anything that writes outside the tree — list those as unverified instead. Also run bash scripts/resolve-tech-stack.sh "$PWD": a constitution naming a different stack, or only the root's stack in a polyglot repo with per-subtree pins, is a currency finding.
2. Shim integrity. When CLAUDE.md is a shim, confirm @AGENTS.md is present and bare (inside a code fence or backticks it is inert). A shim has no ## Critical Rules by design — not rot. Nested package files get a full pass only when they carry package-local content.
3. Judge what scripts cannot: architecture clarity, captured gotchas, conciseness, and vague rules ("write good tests") that need a concrete replacement. A line that is true but belongs elsewhere gets Move → (README, a rule file, a skill, the spec); the test: would a newcomer act differently because of this line here? No numeric grade — name the line and the reason.
4. Report, then stop. List every STALE path and failed command with its line, the judgement findings, and proposed changes. A clean file is reported as clean; never invent issues. Ask: "Approve these changes? (yes / partial / no)"
5. Apply only the approved subset as one Edit per change. Removals need per-line approval; "approve all" does not cover deletions. Then re-run step 1 on the edited file and confirm the line count moved less than 10%.