agentleFS
moberghrmoberghr/mtk-agent-toolkit/.claude/skills/mtk-setup/SKILL.md

mtk-setup

Skill8 starsChanged 3 days agoMITView on GitHub

One-stop setup entry point that bootstraps a repo or re-runs architecture audit

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
  1. Very specific:

    Read the target SKILL.md and follow every step inline, including its Verification section.

    line 74

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 the CLAUDE.md shim), .claude/tech-stack and architecture-principles.md.
  • Audit (--audit): regenerate architecture-principles.md and conventions.md after 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-run first 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

FlagMeaning
--audit / --audit-onlyAudit only (no stack detection, no AGENTS.md generation)
--mergeMulti-repo unification (implies audit)
--previewBootstrap only: show proposed changes, ask before writing
--non-interactiveBootstrap/refresh: skip the interview; engineer-edited files defer to Needs review
--no-verify-commandsBootstrap only: skip STEP 3.5a command execution
--update-guidelinesBump the coding-guidelines pin. Does not re-run bootstrap.
--refreshDelegate to setup-refresh
--dry-runOnly with --refresh: print the plan, write nothing
--checkDelegate to setup-refresh Check mode. Writes nothing outside .claude/.mtk-cache/.

Combination rules — reject with a clear message:

  • --update-guidelines combines with nothing.
  • --merge excludes --non-interactive.
  • --refresh and --check exclude each other, --audit, --merge and --update-guidelines.
  • --dry-run requires --refresh.
  • --no-verify-commands is bootstrap-only.
  • --converge was retired into --check: say so and run --check.

STEP 1: Decide the Target

ArgumentTarget
--update-guidelinesbash 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 via AskUserQuestion — "No tech stack detected — this looks like a first-time setup. Audit alone won't generate AGENTS.md. Run /mtk-setup with 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-setup with 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, the CLAUDE.md shim, .claude/tech-stack and architecture-principles.md exist
  • 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.