feat: ship agentfile as a Claude Code plugin

[dennishavermans]

A linter nobody remembers to run reports nothing, which is the failure agentfile exists to describe. The configuration it reads is configuration someone is editing in Claude Code, so it can speak at the moment of the edit instead of waiting to be invoked.

claude plugin marketplace add dennishavermans/agentfile
claude plugin install agentfile@agentfile

The repository is its own marketplace, so this needs no listing from anyone.

What installs

A skill, covering the permission-matching behaviour that makes a rule grant more than it reads: that everything before the first * is matched as written and is the only thing limiting the rule, and the five rule shapes that follow from it.

Every measured claim in it is copied from diagnostic text already shipped and already corrected in 2.3.1, rather than restated. It carries nothing that has not been through review once.

A hook on PostToolUse, running after an edit to CLAUDE.md, AGENTS.md, .mcp.json, .claude/ or .cursor/, reporting only the findings in the file that changed.

Design decisions

It informs, never blocks. A hook that refuses a write on a warning gets uninstalled the same day, and a finding is advice rather than a verdict: static analysis cannot see intent. Every failure path exits 0, so a missing binary cannot wedge an edit.

It reports only the edited file. check has no per-file scoping, so the hook filters the JSON report by path. Without that, one edit would print the whole repository's backlog.

Python, not shell. Matching the hook scripts in Anthropic's own plugins. An earlier shell version embedded Python for the JSON filtering and failed silently on quoting, which is the kind of thing that ships broken.

Prefers a local binary. AGENTFILE_BIN, then agentfile on PATH, then npx. Faster, works offline, and testable.

Drift

The plugin carries the same two drift points the pre-commit hooks did: a pinned CLI version and a version of its own. Both are now covered by the existing invariant test, verified non-vacuous by reverting each and watching it fail.

Verification

• claude plugin validate passes on the plugin and on the marketplace manifest.
• The hook was exercised across five arms: an edited settings file, an edited skill, an unrelated file, a clean repository, and malformed input. The one that matters is the second: editing the skill reports its own two findings and does not leak the settings file's.
• Full suite 1071 passed, up from 1069.

Not included

Filling agentfile's own .claude/skills/. .claude/ is gitignored here, so keeping per-developer configuration out of the repository is a deliberate choice, and adding files would contradict it.