mtk-setup
Skill8 starsChanged 3 days agoMITView on GitHub
One-stop setup entry point that bootstraps a repo or re-runs architecture audit
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- batch-fixSkill
- brainstormingSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- context-engineeringSkill
- fixSkill
- handoffSkill
- implementSkill
- incremental-implementationSkill
- instructionsSkill
- lessonsSkill
- mtk-doctorSkill
- mtkSkill
- planning-and-task-breakdownSkill
- pre-commit-reviewSkill
- prior-work-checkSkill
- promote-lessonSkill
- repo-healthSkill
- research-contextSkill
- security-and-hardeningSkill
- setup-auditSkill
- setup-bootstrapSkill
- setup-refreshSkill
- spec-drift-detectionSkill
- spec-driven-developmentSkill
- subagent-implementationSkill
- tech-stack-dotnetSkill
- tech-stack-pythonSkill
- tech-stack-typescriptSkill
- verification-before-completionSkill
- workflow-artifactsSkill
- writing-skillsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 74
Read the target SKILL.md and follow every step inline, including its Verification section.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
MTK Setup — Unified Entry Point for Bootstrap and Audit
You dispatch to the right setup workflow skill based on the argument and the repo's state.
Overview
- Bootstrap (no flags): detect the stack, pull the pinned coding guidelines, audit once, generate
AGENTS.md(plus theCLAUDE.mdshim),.claude/tech-stackandarchitecture-principles.md. - Audit (
--audit): regeneratearchitecture-principles.mdandconventions.mdafter architectural change. - Merge (
--merge): unify per-repo audits in.claude/references/audits/into one team-wide doc. - Refresh (
--refresh): drift-scoped refresh of every generated artifact, proposing diffs for engineer-edited files. - Check (
--check): read-only — the staleness plan as a CI gate, plus a graded report of principles whose evidence anchors no longer resolve. - Update guidelines (
--update-guidelines): bump the coding-guidelines pin to the remote HEAD SHA.
When To Use
- First time onboarding a repo →
/mtk-setup. - Architecture drifted →
/mtk-setup --audit. - Several repos' audits to unify →
/mtk-setup --merge. - Generated docs drifted →
/mtk-setup --refresh(--dry-runfirst to preview). - CI, or "are the docs still accurate, and where has the code left the agreed principles?" →
/mtk-setup --check.
Workflow
STEP 0: Parse Arguments
| Flag | Meaning |
--audit / --audit-only | Audit only (no stack detection, no AGENTS.md generation) |
--merge | Multi-repo unification (implies audit) |
--preview | Bootstrap only: show proposed changes, ask before writing |
--non-interactive | Bootstrap/refresh: skip the interview; engineer-edited files defer to Needs review |
--no-verify-commands | Bootstrap only: skip STEP 3.5a command execution |
--update-guidelines | Bump the coding-guidelines pin. Does not re-run bootstrap. |
--refresh | Delegate to setup-refresh |
--dry-run | Only with --refresh: print the plan, write nothing |
--check | Delegate to setup-refresh Check mode. Writes nothing outside .claude/.mtk-cache/. |
Combination rules — reject with a clear message:
--update-guidelinescombines with nothing.--mergeexcludes--non-interactive.--refreshand--checkexclude each other,--audit,--mergeand--update-guidelines.--dry-runrequires--refresh.--no-verify-commandsis bootstrap-only.--convergewas retired into--check: say so and run--check.
STEP 1: Decide the Target
| Argument | Target |
--update-guidelines | bash scripts/update-guidelines.sh --bump (below) |
--check | .claude/skills/setup-refresh/SKILL.md, ## Check Mode |
--refresh | .claude/skills/setup-refresh/SKILL.md (pass --dry-run, --non-interactive) |
--merge | .claude/skills/setup-audit/SKILL.md with --merge |
--audit / --audit-only | .claude/skills/setup-audit/SKILL.md |
| none of the above | .claude/skills/setup-bootstrap/SKILL.md (pass --preview, --non-interactive, --no-verify-commands) |
--update-guidelines: run bash scripts/update-guidelines.sh --bump and print its output verbatim. The script resolves the remote HEAD to a 40-char SHA, fetches every pinned file at that SHA, hashes all of them before writing, and writes nothing on any failure. It never writes into the plugin cache: a pin read from $CLAUDE_PLUGIN_ROOT lands in the repo-local .claude/mtk-version.json. Exit 1 is a failed fetch or unreachable remote: report it, and the pin is unchanged. Then tell the engineer: "Guidelines pin updated in <file the script named>. Run /mtk-setup --audit or /mtk-setup to apply them." Never auto-invoke bootstrap.
Un-bootstrapped repo (no .claude/tech-stack):
--audit: warn viaAskUserQuestion— "No tech stack detected — this looks like a first-time setup. Audit alone won't generate AGENTS.md. Run/mtk-setupwith no flags for a full bootstrap. Proceed with audit only? [y/N]"--refresh/--check: do not offer to proceed. Say: "This repo has not been bootstrapped — run/mtk-setupwith no flags first."
STEP 2: Follow the Target Skill
Read the target SKILL.md and follow every step inline, including its Verification section.
STEP 3: Report
✅ MTK Setup: [bootstrap|audit|merge|refresh|check|update-guidelines] complete in [duration]. See [output file(s)].MTK File Resolution
Resolve MTK skill/reference/script paths per .claude/references/mtk-file-resolution.md unless the router already stated MTK_ROOT=<path> this session; CLAUDE.md, .claude/tech-stack, .claude/rules/, tasks/, docs/, .mtk/ stay project-relative.
Verification
- Target chosen from the flags; invalid combinations rejected
- Target skill's Verification section executed
- Bootstrap:
AGENTS.md, theCLAUDE.mdshim,.claude/tech-stackandarchitecture-principles.mdexist - Merge: source audits in
.claude/references/audits/untouched - Check: nothing written outside
.claude/.mtk-cache/; plan exit code propagated - Update guidelines: the script's exit code reported; pin file named
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

