Make this git repository ready for AI — so AI coding agents can work in it from the first run. Audit its AI coding readiness, score it out of 10, then transform it in place: CI gates, AGENTS.md, a spec-driven workflow. Every step verifiable, never breaking the existing build.
An AI-native repository generally comes with complete quality gates and AI guidance: pre-commit hooks, lint / formatter checks that actually run, CI that agrees with the local gates, an AGENTS.md that tells the agent how things run, and a spec-driven contract (SDD templates) — to name a few. New quality gates, as they emerge, join the readiness score.
Spooner is an Agent Skills (SKILL.md) built for coding agents. Named after Detective Del Spooner in I, Robot (2004), whose left arm is robotic and serves him well — Spooner evaluates which of the above your repository is missing (AI readiness /10), adds them incrementally, and keeps them from drifting.
| Command | What it does | When |
|---|---|---|
audit |
Detect and score AI coding readiness (repeatable — a health check) | Any repo, anytime |
transform |
Incremental, verifiable, rollback-able transformations (stack-aware CI gates incl. the manifest drift gate / AGENTS.md / SDD) | Once — the surgery |
check |
Continuously detect drift (repeatable, with records) | Every CI run |
sync |
Re-sync installed templates to the current tool version (version-aware, one-click) | When the tool advances |
badge |
Render a readiness badge matched to your README's badge style (5 shields styles, links to the audit report) | After transform, whenever the score moves |
| Stack | detect + audit | transform (gates + CI + AGENTS.md) |
|---|---|---|
| node (incl. React/Vue/Next) | ✅ | ✅ npm lifecycle |
| python | ✅ | ✅ python3 -m unittest discover |
| go | ✅ | ✅ go build/test ./... |
| java (Maven + Gradle) | ✅ | ✅ mvn test / gradle build |
| rust | ✅ | ✅ cargo build/test (fmt/clippy gates) |
| ruby / php / swift / dotnet | ✅ (audit under-scores only) |
All 10+ mainstream coding agents natively support the SKILL.md standard; AGENTS.md is nearly universal:
| Agent | AGENTS.md | Skills directory |
|---|---|---|
| Claude Code | via CLAUDE.md (symlink) | .claude/skills/ |
| OpenAI Codex | native | .agents/skills/ |
| OpenCode | native | .opencode/skills/ |
| Qwen Code | via config | .qwen/skills/ |
| Kimi Code | native | .kimi-code/skills/ |
| CodeBuddy | fallback (CODEBUDDY.md primary) | .codebuddy/skills/ |
| Trae | via toggle | .trae/skills/ |
| Qoder | native | SKILL.md native |
| Cursor | native | .cursor/skills/ |
| VS Code | native | .github/skills/ |
Universal strategy: AGENTS.md at repo root holds persistent facts (≤200 lines), SKILL.md holds on-demand procedures, per-agent rules files handle single-tool constraints.
The skill is a single directory (skills/spooner/) — no build step, just Node.js >= 22.18 (scripts are TypeScript run natively via type stripping).
npx skills add ZM-BAD/spoonerThe skills CLI copies skills/spooner/ into your agent's skills directory and detects your agent from the environment. Useful flags:
| Flag | Meaning |
|---|---|
-g / --global |
install to the user-level skills directory (available to all projects) |
-a / --agent <agent> |
target a specific agent (claude-code, codex, opencode, …) |
-s / --skill <name> |
install only the spooner skill |
Copy the skills/spooner/ directory into your agent's skills directory (see the compatibility table above). User-level examples:
# Claude Code — all projects
mkdir -p ~/.claude/skills
cp -R skills/spooner ~/.claude/skills/
# OpenAI Codex — all projects
mkdir -p ~/.agents/skills
cp -R skills/spooner ~/.agents/skills/
# OpenCode — all projects
mkdir -p ~/.config/opencode/skills
cp -R skills/spooner ~/.config/opencode/skills/To share the skill with a specific repo, copy it to the project-level path from the table above (e.g. .claude/skills/spooner/).
List skills in an agent session (/skills in Claude Code and Codex), then run the audit on a repo:
node skills/spooner/scripts/audit.tsspooner/
├── AGENTS.md / CLAUDE.md # agent contract (single source of truth; CLAUDE.md is a symlink)
├── README.md / zh-CN.md # bilingual docs
├── docs/ # local-only internal design archive (not published)
├── specs/ # SDD work contracts (live docs: README + templates/ + <nnn>-<name>/)
├── skills/spooner/ # the distributable unit: SKILL.md + scripts/ + templates/
│ ├── SKILL.md # Agent Skills standard entry (name matches directory)
│ ├── scripts/ # zero-dependency scripts (TS run natively by Node)
│ └── templates/ # output templates (AGENTS.md, etc.)
└── .github/workflows/ # CI: pre-commit, typecheck, commitlint, SKILL.md validation
Spec-driven (SDD): every feature starts as a spec in specs/<nnn>-<name>/spec.md (proposed → approved → in-progress → shipped), implemented in independently verifiable slices. Template: specs/templates/spec.md.
npm run typecheck # tsc --noEmit (TypeScript 6, zero build)
npm run lint:md # markdownlint-cli2
npm run check # typecheck + lint:md + tests
pre-commit install --hook-type commit-msg # enforce Conventional Commits on every commit
pre-commit run --all-files
node skills/spooner/scripts/detect.ts # slice 1: stack detectionConstraints: TypeScript 6 only (major locked — the toolchain still requires the 6.0 API until TS 7.1), erasable syntax only (no enum/namespace), zero-dependency scripts, Conventional Commits (commitlint enforced).
Distributed from this GitHub repository — npx skills add ZM-BAD/spooner installs the skill directly. The Claude Code plugin marketplace and community registries are planned next.
| Doc | Content |
|---|---|
AGENTS.md |
Agent contract (single source of truth; CLAUDE.md is a symlink) |
specs/README.md |
SDD workflow: states, conventions, two-layer structure |
specs/ROADMAP.md |
Planning index: current / next / vision / ideas |
specs/0001-m1-audit-core/spec.md |
M1 audit contract: scoring matrix, report schema, acceptance |
skills/spooner/SKILL.md |
The distributable skill entry |
Thanks to the users whose trial feedback shaped this project — each release lists the people whose reports were fixed:
