🧰 Skill Madness

---

🚪 New here, or not sure which skill to reach for? Type /madness in Claude Code and just say what you want. It reads your intent, picks the right starting skill out of all 80, confirms before anything expensive, and launches it — so you never have to memorize the catalog. One front door for the whole toolkit.

Maintainers / agents: see START-HERE.md for current status and which docs are canonical.

---

✨ Why this exists

Every AI coding tool ships the same traps. One agent, one context window, one set of files — fine for a small project, brittle for anything bigger than a single context can hold. They stop at the first draft — when the tests are still red, you’re the one re-prompting “still failing, try again” until it finally goes green. And every tool reinvents the same wheel — Cursor wants .mdc, Aider wants CONVENTIONS.md, Windsurf wants .windsurfrules, Claude Code wants SKILL.md — so any prompt library you build gets stranded on whichever host you wrote it for.

Skill Madness attacks all three. The orchestrator decomposes a complex build into a 14-phase plan, makes integration surfaces machine-readable before anyone writes code, dispatches role agents in parallel with strict file ownership, and refuses to ship until a separate QE agent signs off via a structured report. Autonomous loops then keep the work going after that first pass — driving tests to green, coverage to a target, or a contract to conformance, with guardrails that make them converge instead of thrash. And the skill library underneath authors once in the canonical SKILL.md format — the same skills install into eleven different AI coding tools without copy-paste drift.

• 👑 The orchestrator is the entry point — a single 14-phase playbook covering team sizing, runtime detection, contract authoring, parallel dispatch, integration validation, QA gate, and handoff. It’s the skill that turns a one-line ask into a coordinated multi-agent build.
• 📜 Contract-first — contract-author writes OpenAPI / AsyncAPI / Pydantic / TypeScript / JSON Schema before a line of implementation. contract-auditor verifies every shipped module against the spec. Agents can’t drift; the contract is the truth.
• 🤖 Ten role agents, exclusive ownership — backend, frontend, infrastructure, QE, security, docs, observability, db-migration, performance, code-review. Each declares owns.directories / owns.files in its frontmatter. No two agents touch the same path. Conflicts get resolved before spawn, not after.
• 🛡️ QA gate that blocks — qe-agent emits a qa-report.json with critical / high / medium / low findings plus contract-conformance and security scores. The orchestrator gates the merge on the report. Agents can’t self-declare “done.”
• 🔁 Autonomous loops that converge — 13 loop skills keep Claude working until something is provably true: fix-until-green won’t stop until tests + lint + typecheck pass (and can’t cheat the gate), coverage-loop grows the suite to a target without gaming it, contract-conformance-loop builds until a fresh-context evaluator agrees the spec is met, and babysit / self-healing-loop / nightly-docs-and-changelog run on a schedule. Every one is a configuration of loop-controller’s guardrail stack — iteration cap, token budget, no-progress breaker, stop condition — so they finish instead of thrashing. See the loops →
• 🪄 One front door — madness is the router: type /madness, describe the task, and it picks the right starting skill out of all 80 and launches it. The cure for “which skill was that again?” across a 80-skill library.
• 🪜 Progressive disclosure — frontmatter (~100 tokens) always loaded, body loaded on trigger, references loaded on demand. A 80-skill library stays cheap to host.
• 🔁 Two-runtime degradation — Agent Teams (parallel tmux) → subagents (Task tool) → sequential. The orchestrator picks the highest mode the host supports; role skills work standalone in any of them.
• 🧰 80 skills, seven categories, all CI-linted — the orchestrator, 10 role agents, 2 contract skills, 9 meta-skills (including madness, the front-door router, and model-adaptation), 4 git-workflow skills, 41 cross-cutting workflow skills (plan-builder, repo-deep-dive, ui-brief, mermaid-charts, …), and 13 autonomous-loop skills. Frontmatter, body length, and cross-skill ownership are all gated on every push.
• 🌐 Portable format, honest subset — SKILL.md is the canonical source; converters emit Claude Code, Copilot, Cursor, Aider, Windsurf, OpenCode, Qwen, OpenClaw, Gemini CLI, Antigravity, Kimi, and Agent Skills (Codex) formats. The native orchestrator and autonomous loops retain Claude Code’s runtime primitives. All ten roles and contract-auditor now offer explicit bounded solo branches; native ownership and QE dispatch remain intact. Portable export is delivery, not live-host or independent-review certification. See Also works on eleven other hosts.

Status — read before you pitch this to anyone:

• The orchestrator + 80-skill library is the mature part. PSFS author validation, ownership/cross-reference checks, an Ubuntu lint gate plus a non-blocking macOS smoke on every push. Body diagnostics report physical/nonblank lines and approximate tokens, not measured host context cost.
• The 13 autonomous loops are the newest layer. All built on one loop-controller guardrail harness and CI-linted. The build/verify loops (fix-until-green, coverage-loop, contract-conformance-loop) are the most exercised; the scheduled ones (self-healing-loop, dependency-health-loop) are powerful but younger — keep a human in the loop on anything irreversible.
• Claude Code is the native orchestration target. Teams/agents/workflows and the qa-report.json gate remain its native path. This audit verified local tooling and fake-root delivery, not current live-host dispatch or model efficacy. The other ten converter targets receive the portable subset, not native parallel dispatch certification.
• Lossy conversion is announced. When a skill is converted to a non-Claude-Code host, orchestration-only fields (allowed_tools, owns, composes_with, spawned_by, requires_agent_teams) are stripped with a stderr line per skill. Skills marked requires_claude_code: true are skipped entirely for those targets. See contracts/installer/per-tool-output-spec.md.

---

🚀 Quick Start

Prerequisites

Install for Claude Code

Two install paths. Pick one.

Option A — Claude Code plugin manager (recommended for users)

From inside Claude Code:

/plugin marketplace add ivy00johns/Skill-Madness
/plugin install skill-madness@skill-madness

That installs all 80 skills into Claude Code’s plugin storage. No clone, no symlink, no edits-to-the-repo workflow. Use this if you just want the skills.

To update later: /plugin update skill-madness.

Option B — Clone + /sync-skills (recommended for contributors)

Clone, then run /sync-skills from inside Claude Code. It creates flattened symlinks at ~/.claude/skills/ so edits in the repo are live in every session — no rebuild step.

git clone https://github.com/ivy00johns/Skill-Madness.git
cd Skill-Madness

# Inside Claude Code:
/sync-skills

If you’d rather copy than symlink, the underlying script accepts --copy instead of --link. See skills/workflows/sync-skills/SKILL.md.

Use this if you want to author skills, iterate on them, or contribute upstream.

Install for any of the other ten hosts

Two scripts. The first translates the canonical SKILL.md files into twelve host-native shapes; the second installs the converted artifacts into whichever hosts it detects on your machine.

./scripts/convert.sh   # skills/**/SKILL.md  →  integrations//...
./scripts/install.sh   # integrations/ →  ~/./, .cursor/rules/, etc.

install.sh is interactive when run in a TTY and auto-detects from environment variables in CI. See Also works on eleven other hosts for the per-host format matrix and what gets stripped on conversion, and scripts/README.md for flag-level docs.

Use it

Tell Claude Code to build something with multiple agents:

"Build a chat app with React frontend and FastAPI backend — use an agent team."

The orchestrator skill triggers automatically: it sizes the team, generates contracts, spawns parallel agents in isolated worktrees, gates the build on qa-report.json, and returns when QE signs off.

Or set it loose on a goal and let a loop converge on its own:

"Fix the failing tests and don't stop until everything's green."  → fix-until-green
"Get test coverage up to 85% without gaming the metric."          → coverage-loop
"Keep this PR rebased and green while review comes in."           → /loop 5m /babysit
"Map this whole codebase and write me the architecture."         → codebase-exploration-loop

Or invoke any skill standalone:

"Review this code for security vulnerabilities."   → security-agent
"Set up Docker and CI/CD for this project."        → infrastructure-agent
"Write k6 load tests for the /search endpoint."    → performance-agent
"Profile this codebase and write me a CLAUDE.md."  → project-profiler
"Generate a UI brief for a refresh of /settings."  → ui-brief

Not sure which skill fits? Don’t guess — let the front door route you:

/madness build a CLI that syncs two folders, with tests

madness reads the intent, picks the right starting skill, confirms before anything expensive (a swarm, an overnight loop, a full build), and hands off.

---

🧬 Architecture

The orchestrator sits above seven skill categories — every build pulls from this library, every category lints clean, and the library’s portable subset converts to the ten non-Claude-Code hosts.

flowchart TB
    orch["👑 orchestrator14-phase build playbook · runtime detectionteam sizing · circuit breaker · handoff protocol"]:::entry

    subgraph contracts["📜 contracts/ — 2 skills"]
        direction TB
        ca[contract-author]
        cau[contract-auditor]
    end

    subgraph roles["🤖 roles/ — 10 agents · exclusive file ownership"]
        direction TB
        be[backend]
        fe[frontend]
        infra[infrastructure]
        qe["qe(QA gate)"]:::gate
        sec[security]
        rdocs[docs]
        obs[observability]
        dbm[db-migration]
        perf[performance]
        cra[code-review]
    end

    subgraph meta["🧠 meta/ — 9 skills"]
        direction TB
        md["madness(front door)"]:::entry
        sx[skill-explorer]
        sw[skill-writer]
        sr[skill-review]
        su[skill-update]
        mda[model-adaptation]
        sc[skill-catalog]
        stg[skill-triage]
        sev[skill-eval]
    end

    subgraph gitcat["🔁 git/ — 4 skills"]
        direction TB
        gcm[git-commit]
        gpr[git-pr]
        gpf[git-pr-feedback]
        gpmc[git-post-merge-cleanup]
    end

    subgraph workflows["⚙️ workflows/ — 41 skills"]
        direction TB
        pb[plan-builder]
        cm[context-manager]
        dc[dependency-coordinator]
        dch[deployment-checklist]
        pp[project-profiler]
        wr[wiki-research]
        rdd[repo-deep-dive]
        lw[llm-wiki]
        ub[ui-brief]
        cdb[claude-design-brief]
        mc[mermaid-charts]
        rs[render-sanity]
        dl[diagnose-loop]
        more["+ 28 more"]
    end

    subgraph loops["🔁 loops/ — 13 skills"]
        direction TB
        lc[loop-controller]
        fug[fix-until-green]
        otl[orchestrator-task-loop]
        ccl[contract-conformance-loop]
        bs[babysit]
        cov[coverage-loop]
        pfl[perf-loop]
        shl[self-healing-loop]
        mig[migration-loop]
        ndc[nightly-docs-and-changelog]
        dhl[dependency-health-loop]
        cel[codebase-exploration-loop]
        rcl[repo-cleanup-loop]
    end

    orch --> contracts
    orch --> roles
    orch --> meta
    orch --> gitcat
    orch --> workflows
    orch --> loops

    classDef entry fill:#7c3aed,stroke:#4c1d95,color:#fff,stroke-width:2px
    classDef gate fill:#dc2626,stroke:#7f1d1d,color:#fff,stroke-width:1.5px

How a build flows

A one-line build request enters the orchestrator and exits as a shipped artifact only after the qe-agent writes a passing qa-report.json. Every other path blocks the merge.

flowchart TB
    user(["🧑 You"]) -->|"build X — use an agent team"| orch[👑 orchestrator]
    orch --> detect[/"detect runtimeAgent Teams · subagents · sequential"/]
    detect --> size[/"size team"/]
    size --> contracts["📜 contract-authorOpenAPI · Pydantic · TypeScriptwritten BEFORE any implementation"]:::contract

    contracts --> dispatch{{"⚡ parallel dispatchexclusive file ownership · no overlapping writes"}}

    subgraph parallel["isolated worktrees"]
        direction LR
        be["🛠 backendowns api/"]
        fe["🎨 frontendowns web/"]
        infra["📦 infrastructureowns infra/"]
        docs["📚 docsowns docs/"]
    end

    dispatch --> be
    dispatch --> fe
    dispatch --> infra
    dispatch --> docs

    be --> validate
    fe --> validate
    infra --> validate
    docs --> validate

    validate["🔬 contract-auditor+ qe-agent + security-agent"]:::validate
    validate --> gate{"🚦 qa-report.jsongate"}:::gate
    gate -- "CRITICAL findings" --> block[/"⛔ block merge"/]:::fail
    gate -- "all checks pass" --> ship[/"🚀 ship"/]:::pass

    classDef contract fill:#1e40af,stroke:#1e3a8a,color:#fff,stroke-width:2px
    classDef validate fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef gate fill:#f59e0b,stroke:#b45309,color:#fff,stroke-width:2px
    classDef fail fill:#dc2626,stroke:#7f1d1d,color:#fff
    classDef pass fill:#16a34a,stroke:#14532d,color:#fff

---

🔁 Autonomous loops

The newest part of Skill Madness — and the fastest way to feel why it exists. A loop points Claude at a goal with a verifiable stop condition and a mandatory guardrail stack, then lets it run until the goal is provably met. No more babysitting “still failing, try again.”

Every loop is a configuration of loop-controller, the foundation harness that picks the right primitive for the job — /goal, /loop, a Stop-hook, a bash “Ralph” loop, or a dynamic workflow — and wires in the guardrails so the loop converges instead of thrashing or running up the bill.

🟢 Build & verify — run until it’s green:

🗓️ Operate & maintain — run on a schedule:

🔎 Understand & coordinate:

🛡️ Loops are gated by design. Every loop inherits loop-controller’s guardrails: a hard iteration cap, a token budget, a no-progress circuit breaker, and a stop condition checked by a separate fresh-context evaluator so the worker can’t grade its own homework. Anything irreversible — pushing to prod, force-deleting work — pauses for a human. Read the harness: skills/loops/loop-controller/SKILL.md.

---

🧰 Skill catalog

80 skills organized into seven categories. Frontmatter is validated by PSFS author schema; lint checks declared ownership and cross-references. Body guidance is advisory: diagnostics separate physical/nonblank lines, words and UTF-8-bytes/4 approximate tokens. Resource inventories check literal local references and declare external dependencies, not live-host acceptance.

---

📂 Project structure

.
├── README.md                         # this file
├── CLAUDE.md                         # project guidance for Claude Code
├── AGENTS.md                         # shared instructions for AI agents
│
├── skills/                           # the canonical skill library (80)
│   ├── orchestrator/                 # 1 — entry point
│   ├── roles/                        # 10 — implementation agents
│   ├── contracts/                    # 2 — contract-author / contract-auditor
│   ├── meta/                         # 7 — skills that manage skills (incl. madness, model-adaptation)
│   ├── git/                          # 4 — git workflow conventions
│   ├── workflows/                    # 34 — cross-cutting process skills
│   └── loops/                        # 13 — autonomous-loop skills
│
├── scripts/                          # multi-tool installer
│   ├── convert.sh                    # SKILL.md → 11 host-native formats
│   ├── install.sh                    # integrations/ → host install dirs
│   ├── lint-skills.sh                # frontmatter + cross-skill validation
│   ├── lib/                          # frontmatter / platform / slug / term helpers
│   └── README.md                     # per-host destinations and flags
│
├── hooks/                            # lifecycle-hook layer (Claude Code only, 6 hooks)
│   ├── hooks.manifest.json           # registry: hook id, event, profiles, blocking
│   ├── run-with-flags.sh             # single entrypoint; dispatches scripts/.sh
│   ├── scripts/                      # per-hook implementations (qa-gate, catalog-sync, …)
│   └── lib/                          # shared hook helpers
│
├── integrations/                     # generated outputs (one dir per host)
│   ├── claude-code/  copilot/  cursor/  aider/  windsurf/
│   ├── opencode/  qwen/  openclaw/  gemini-cli/  antigravity/  kimi/
│
├── contracts/installer/              # installer specs
│   ├── skill-source-format.md        # canonical SKILL.md schema
│   ├── per-tool-output-spec.md       # per-host fidelity matrix
│   ├── install-locations.md          # where each host expects skills
│   └── lint-rules.md                 # what the linter enforces
│
├── spec/                             # the portable frontmatter standard
│   ├── PSFS.md                       # Portable Skill Frontmatter Spec v1.1.0
│   └── frontmatter.schema.json       # JSON Schema 2020-12 reference validator
│
├── tests/installer/                  # bats-core tests for convert/install/lint
└── .github/workflows/lint-skills.yml # Ubuntu gate + macOS smoke CI

---

🎁 Also works on eleven other hosts

Native hook execution and the twelve concrete autonomous loops retain their Claude-Code runtime path. The orchestrator and loop-controller keep that native path and also export to hosts that cannot spawn agents (sequential role packets that run the whole build after one plan approval; in-session iterations or run_guarded.py around a bounded adapter). The ten role skills and contract-auditor now also have explicit bounded solo branches: user-supplied scope/contracts, the same ownership/checklists, and honest blocked/independence reporting without invented Agent calls. Thus 55 of the 80 skills export to the eleven other converter targets. Export count is not runtime certification: resource delivery is covered by local fake-root regressions; live-host efficacy and mechanical unattended controls remain tracked in docs/REMAINING-WORK.md. The broader F1 generator framework remains parked.

The single-source model is deliberate, and there’s a concrete counter-example for why: microsoft/SkillOpt shipped the opposite design — five bespoke per-host integrations (claude-code, codex, copilot, devin, openclaw) — and was already drifting within months of release: backend-enum mismatches between plugins, and an openclaw adapter broken-by-design against its own engine. One canonical SKILL.md plus converters means a fix lands once instead of five times.

Two scripts handle it:

./scripts/convert.sh   # skills/**/SKILL.md  →  integrations//...
./scripts/install.sh   # integrations/ →  ~/./, .cursor/rules/, etc.

install.sh is interactive when run in a TTY and auto-detects from environment variables in CI. See scripts/README.md for per-host destinations, scopes, and flags.

Lossy by design. Claude-Code-specific orchestration fields (allowed-tools, owns, composes_with, spawned_by, requires_agent_teams) are stripped on conversion to the other ten hosts — those hosts don’t run multi-agent dispatch with file-ownership exclusivity, so the metadata would be noise. You’ll see one [host] stripped allowed-tools/owns from line per affected skill on stderr. Skills marked requires_claude_code: true are skipped entirely for non-Claude-Code targets.

Credit where it’s due. The eleven-host installer pattern, the detect_() probes, the interactive selection UI, the slug pipeline, and the OpenClaw soul/agents split are all adapted from msitarzewski/agency-agents (MIT). Full attribution and the list of pieces that came across vs. were rewritten lives in ACKNOWLEDGMENTS.md. The orchestrator, role agents, contracts, QA gate, and the rest of the skill library are independent.

---

💻 CLI / scripts reference

---

🪝 Hooks

Skill Madness ships a small hooks layer under hooks/ that turns the orchestrator’s doctrine — the QA gate, formatting, profile injection — into enforcement. Hooks are modeled on the gated-hook design but built in the repo’s own bash + python3 (stdlib-only) idiom. Today only Claude Code has a native lifecycle-hook runtime, so hooks are emitted for Claude Code and skipped (logged unsupported) for the other ten hosts.

The six hooks

Everything routes through one entrypoint — hooks/run-with-flags.sh — which reads the gating env vars and hooks.manifest.json, then dispatches hooks/scripts/.sh (or no-ops exit 0 if disabled).

Profiles & disabling

Two env vars tune the whole graph:

• ATS_HOOK_PROFILE ∈ {minimal, standard, strict} (default standard).
  • minimal → qa-gate only (1 hook).
  • standard → qa-gate + post-edit-format + session-start-profile + catalog-sync + skill-usage (5 hooks).
  • strict → all six; qa-gate also treats a missing report as a block.
• ATS_DISABLED_HOOKS → comma-separated hook ids to force-off, e.g. post-edit-format,pre-commit-lint.

Only qa-gate ever blocks, and only on a real gate failure. It signals a block the Claude Code way — printing {"decision":"block","reason":"…"} to stdout and exiting 0.

Install & enable

scripts/convert.sh --tool claude-code copies hooks/ into integrations/claude-code/hooks/ and generates integrations/claude-code/hooks.json (Claude Code settings-hook format). scripts/install.sh then copies that tree to a namespaced target — ~/.claude/ats-hooks/ — and writes hooks.json there. Install is non-destructive: it never auto-merges your ~/.claude/settings.json. Instead it prints the exact snippet to merge into the "hooks" key. The wrapper is invoked as:

"$CLAUDE_PROJECT_DIR"/.claude/ats-hooks/run-with-flags.sh 

Lint & test

./scripts/lint-hooks.sh          # validate the hooks tree (manifest, exec bits, headers, profiles)
bash tests/hooks/run-tests.sh    # the bats suite (wrapper gating, qa-gate, convert, lint)

Both run in CI via the Hooks Layer (Ubuntu) job in .github/workflows/lint-skills.yml.

---

🛠️ Development

Run the lint locally

./scripts/lint-skills.sh

That’s the same command the gating Ubuntu CI job runs. If it’s green locally on Linux, the PR will be green — the macOS job is a non-blocking compatibility smoke (continue-on-error).

Add a new skill

1. Use the skill-writer skill: "Generate a new skill for X." — it scaffolds frontmatter + body in the right category dir.
2. Or copy skills/meta/skill-writer/references/body-template.md and fill in by hand.
3. Run ./scripts/lint-skills.sh skills/// until clean.
4. Run /sync-skills (or ./scripts/install.sh --tool claude-code) so Claude Code picks it up.
5. PR — CI gates on full-ecosystem lint.

Edit an existing skill

If you used /sync-skills, the symlinks make edits in skills/ live in ~/.claude/skills/ immediately — no resync needed.

Keep skill bodies under 500 lines. When detail spills over, move it to references/ — that’s what progressive disclosure is for.

---

🩺 Troubleshooting

---

🗺️ Roadmap

• [x] Skill library — 80 skills, seven categories, all linted
• [x] Multi-tool installer — convert / install / lint, eleven host adapters
• [x] CI matrix — Ubuntu lint gate + macOS smoke on every push
• [x] Contract-first specs — OpenAPI / AsyncAPI / Pydantic / TypeScript / JSON Schema templates
• [x] QA gate — qa-report.json schema with critical / high / medium / low blockers
• [x] Two-runtime degradation — Agent Teams → subagents → sequential, host-detected
• [x] Autonomous-loop library — 13 loops on one loop-controller guardrail harness
• [x] /madness front door — one router that reads intent and launches the right skill
• [ ] Image assets — README hero, architecture diagram, host matrix illustration ⏳
• [ ] End-to-end multi-agent verification on non-Claude-Code hosts ⏳
• [ ] Skill marketplace / registry — discoverable installs, version pinning ⏳
• [ ] Per-host CI smoke tests — actually exercise each adapter’s converted skills against a sample host ⏳

---

🧭 Key design decisions

• 📜 One canonical format — SKILL.md with YAML frontmatter is the source of truth; everything else is generated.
• 🚫 Exclusive file ownership — no two role agents own the same file. Conflicts resolved before spawn, not after.
• 🚦 QA gate blocks — critical issues or sub-threshold contract / security scores in qa-report.json fail the build. Self-declared “done” is not accepted.
• 🪜 Progressive disclosure — frontmatter (always loaded) → body (loaded on trigger) → references (loaded on demand). Big libraries, small contexts.
• 🪞 Lossy conversion is announced — every stripped field gets a stderr line per skill per host. The installer never silently drops content.
• 🛡️ Fail loud, fail early — frontmatter schema, ownership conflicts, broken cross-refs are all CI errors, not warnings.
• 🔁 Symlinks > copies — /sync-skills defaults to symlinking so edits in the repo are instantly live in every Claude Code session.
• 📣 Short, specific descriptions — each description says what the skill does, when to use it, and a few phrases users really say (≤400 chars). Hosts budget the skill listing, and an over-long catalog gets its descriptions cut to bare names, which is the worst kind of under-triggering.

---

🤝 Contributing

PRs welcome — new skills, host adapter improvements, lint rules, examples, bug reports.

• New skill? Use skill-writer to scaffold it, then run ./scripts/lint-skills.sh until clean.
• New host adapter? Add the converter to scripts/convert.sh, the installer destination to scripts/install.sh, and a fidelity row to contracts/installer/per-tool-output-spec.md.
• Bug report? Include the failing skill name and the lint output verbatim.

---

📜 License & attribution

MIT — fork, embed, ship commercial products on top, just keep the notice.

The multi-tool installer (scripts/convert.sh, scripts/install.sh, scripts/lib/) adapts code from msitarzewski/agency-agents (also MIT). Full credits, the list of adapted pieces, and the upstream MIT notice live in ACKNOWLEDGMENTS.md.

---