Explore Claude Code mods across the skill families #1497

What

Claude Code shipped mods on 2026-10-02 (v2.1.287, on by default).
This issue is for exploring where mods could make Magpie's skill families better, and where they shouldn't be used.
It is meant for discussion first. Each idea that holds up should get its own issue or PR.

What a mod is

A mod is a Claude Code plugin that contains a JS/TS "hooks module".
Claude Code calls the module's functions inside its own process when events happen.
Each hook works like middleware, ($, e, next), and can do one of three things with an event:

• observe it,
• rewrite it (next({ ...e, ... })), or
• answer it, so Claude Code's default behaviour doesn't run.

Compared with what we use today (skills, settings hooks, MCP), mods can do the following:

You can see what a mod does without running it: claude plugin validate <dir> prints the events it hooks and the API calls it makes.
Mods are tested with claude plugin test (*.test.ts).

Docs

• Overview: https://code.claude.com/docs/en/plugins/mods/overview
• Create a mod: https://code.claude.com/docs/en/plugins/mods/create
• Reference (events, API, render sites, limits, settings): https://code.claude.com/docs/en/plugins/mods/reference
• Managing mods for an organization: https://code.claude.com/docs/en/plugins/mods/admin
• TypeScript declarations (the complete reference): https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts
• Source of the built-in mods (diff, agents-md, sec-default): https://github.com/anthropics/claude-code/tree/main/mods
• Sample mods: https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods

Constraints any Magpie mod has to respect

1. Vendor neutrality. Mods exist only in Claude Code (CLI and the Desktop Code tab). They don't run in Codex or Gemini CLI, and the VS Code panel and claude -p don't draw them.
   So a mod can only enhance a skill. Every skill must still work end-to-end without it (docs/vendor-neutrality.md).
2. Mods are not sandboxed. A mod's $.fs / $.process / $.http calls run as the user, outside the Bash sandbox our secure setup relies on.
   A user-installed mod can also approve tool calls that an ask rule would prompt for.
   Any mod we ship needs a minimal, auditable calls: surface, and the secure-setup docs need to explain the trade-off.
3. No new LLM hop by accident. $.model.complete / $.model.fork / turn.step model routing is an LLM hop under the privacy-LLM rules.
4. Distribution. Magpie already ships as plugins via the marketplace, so a mod can sit in the same family plugin as its skills.
   Orgs running with allowManagedModsOnly won't load it, which is one more reason the skill can't depend on it.

Starting points, by family

Each idea below is a candidate, not a commitment.
The recurring theme is moving deterministic or presentational work out of the model's context.

Setup / secure setup (family:setup)

• Drift check without tokens. Today every skill's pre-flight compares .apache-magpie.local.lock against .apache-magpie.lock inside the model's context.
  A session.start hook could do the comparison in code and show a band ("snapshot drift, run /magpie-setup upgrade").
  The skill's pre-flight then becomes a one-line fallback for non-Claude harnesses.
• /magpie-status as a code-only command. It would print setup-status's report with no Claude turn.
• agent-guard as a mod? The commit-trailer and similar guards are PreToolUse settings hooks today.
  A tool.call mod could hold a call and offer "fix it" instead of only blocking.
  Open question: is that worth losing the shell-script portability? Settings hooks still work and aren't deprecated.
• Signing-wait toast. A toast or band while a signed commit waits for a hardware-key touch.
  It would complement gpg-touch-overlay.sh for terminal-only users.
• setup-isolated-setup-verify / doctor. Report which mods are loaded, and flag any user mod whose calls: include process.* / http.fetch.

Utilities (family:utilities)

• /magpie-skills (list-skills) as a zero-token command.
• Token-cost band while authoring. Show $.session.usage() context and cost while running write-skill / optimize-skill / evals, next to the skill's measured_tokens.
• Commit attribution. An attribution.text hook could emit the trailer that commit-attribution.toml resolves to, so it's correct before agent-guard has to block anything.

Security (family:security)

• Deterministic public-surface scrub. A tool.call hook on gh pr create / gh pr comment / git commit against <upstream> could grep the body file for CVE-, "security fix", "vulnerability", "advisory".
  It would hold the call and show what it found, which makes security-issue-fix's pre-push grep impossible to skip.
• Queue pane. A pane listing needs triage / cve allocated trackers with buttons that start the matching skill.
  Tracker content stays local: it's drawn in the terminal and never posted anywhere.
• Open question: could session.append / prompt.submit help with privacy-LLM PII redaction?
  Probably not, because rewriting what's stored isn't the same as controlling what reaches the model. Worth a written answer either way.

PR management (family:pr-management)

• Review pane for pr-management-code-review. Show drafted inline comments as rows with accept / skip / edit buttons, instead of one AskUserQuestion round-trip per finding.
  The skill keeps posting the accepted set as one review.
• Triage sweep progress band ("PR 7/23 · 3 drafted · 1 closed").
• pr-management-stats rendered as a live pane (Svg on Desktop, Raster in the terminal), not regenerated by the model.

Issue management (family:issue)

• Same shape as PR management: a backlog pane fed by issue-backlog-stats, and a progress band for issue-stale-sweep / issue-triage.

Release management (family:release-management)

• Vote-tally band. Binding / non-binding counts and the time left on the 72h window, refreshed on a $.clock.every timer.
• release-verify-rc checklist pane. One row per check, filled in as the steps finish.
• release-rc-cut keeps printing the signing commands for the RM and never runs gpg. A mod must not change that.

Pairing (family:pairing)

• pairing-multi-agent-review. A pane showing the reviewers' findings side by side.
  turn.step / $.model.fork might replace some of today's orchestration, subject to privacy-LLM constraint 3 above.

Mentoring / contributor growth (family:mentoring, family:contributor-growth)

• Lower priority. Possibly a pane for contributor-activity-sweep results, or for nomination drafts under review.

Proposed next steps

1. Agree on the constraints above, and write them up as a short docs/ page ("When to use a mod in a Magpie family plugin").
2. Pick one pilot with a measurable win. The setup drift check (fewer tokens on every skill run) or the code-review pane (fewer round-trips) look like the best candidates.
3. Wire claude plugin validate --strict and claude plugin test into prek / CI for any directory that contains a hooks module.
4. Open one follow-up issue per idea that survives the discussion.