skill-policy

Provenance, preference, and trust for your agent skills.

You've installed 90 skills into your coding agent. Quick: who wrote the one it just ran? Which of your three overlapping review skills does it pick? And is that skill actually good — or just heavily downloaded?

skill-policy answers all three with one generated index, one small prefs file, and — on Claude Code — a hook that enforces your choices.

npx skill-policy index                 # who wrote what you have installed
npx skill-policy init && sync          # declare preferences, inject them into AGENTS.md
npx skill-policy install claude-code   # enforce them with a real hook
npx skill-policy rate hunt up --note "found root cause fast"

Zero dependencies. One package. MIT.

The problem

• Skills install as bare folders. No author, no source URL — you can't tell the original from a stranger's fork.
• Many skills overlap in purpose: three review skills, two debuggers. Neither you nor the agent has a basis for choosing.
• Download counts measure hype, not helpfulness. Nobody records whether a skill actually worked.

The provenance already exists. The skills CLI writes ~/.agents/.skill-lock.json with a source repo, URL, and version hash for every install. It's just invisible at the moment of choice.

skill-policy surfaces it there.

How it works

Machines write facts. Humans write opinions.

| File | Who writes it | What's in it | |---|---|---| | ~/.skills/skills-index.json | generated — never hand-edit | every installed skill → author, source URL, version hash, description, your rating | | SKILL-PREFS.md | you | author ranking, groups of rival skills with a declared winner, deny/ask/redirect gates | | ~/.skills/ratings.json | machine-managed | hash-pinned records of "this skill actually helped / didn't" |

1. index — know what you're running

Reads the skills lockfile. For skills installed by other means, it infers provenance from git remotes and SKILL.md frontmatter — and honestly reports unknown otherwise.

It also records modelInvocable per skill, read from disable-model-invocation in the skill's own SKILL.md frontmatter. Some authors mark skills human-only; agents shouldn't attempt them, and the AGENTS.md block says so.

2. SKILL-PREFS.md — say what you prefer

---
version: 1
prefer-authors: [mattpocock/skills, tw93/Waza]   # best first
groups:
  bug-hunting:
    skills: [hunt, diagnosing-bugs]
    winner: hunt
gates:
  deny:
    some-heavy-skill: "reason shown when blocked"
  ask: [risky-skill]
  redirect:
    old-skill: new-skill
---

- For any video work, start with /hyperframes — it routes to the right sub-workflow.

Project SKILL-PREFS.md (committed, team-shared) layers over ~/.skills/prefs.md (personal). Project wins per skill; free-form notes concatenate.

3. sync — reach every agent

Maintains a small fenced block in AGENTS.md: your author ranking, group winners, gates, and a pointer telling the agent to consult the index when skills overlap.

Works with any CLI that reads AGENTS.md — Claude Code, Codex, Gemini CLI, Cursor, opencode, and others. check fails CI if the block goes stale.

4. install claude-code — real enforcement

On Claude Code, a PreToolUse hook on the Skill tool:

• annotates every skill invocation in the transcript: [skill-policy] using "hunt" from tw93/Waza (↑ liked)
• denies gated skills, with your reason
• redirects rival-group losers to your declared winner, transparently
• asks before skills on your ask list — or, with strict: true, any skill with unknown provenance
• logs every invocation to ~/.skills/logs/skill-usage.jsonl (stats summarizes it)

5. rate — trust built from real use

npx skill-policy rate hunt up --note "found root cause fast"

Ratings are pinned to the skill's version hash. When the skill updates, the index marks the rating as from an older version — praise never silently carries over to rewritten code.

Agents are instructed to record a rating only when you spontaneously express satisfaction or frustration. They never survey you.

Honest control table

| Agent | Enforcement | |---|---| | Claude Code | Hard — hook denies/redirects/asks before the skill runs | | Codex, Gemini CLI, Cursor, opencode, others | Soft — policy injected via AGENTS.md; the model follows instructions, it isn't forced |

One boundary by design: a human typing /skill always wins. The policy governs the agent's choices; explicit user invocation bypasses it on every agent. Your tool should never argue with you.

Commands

skill-policy init [--global]      scaffold SKILL-PREFS.md
skill-policy index                (re)generate the skills index
skill-policy sync                 refresh index, compile policy, update AGENTS.md
skill-policy check                validate (errors: bad prefs, stale block; warnings: unknown skill names)
skill-policy rate <skill> up|down [--note "..."]
skill-policy stats                invocation counts from the usage log
skill-policy install claude-code  install + register the enforcement hook

Roadmap

• Community ratings — rating records are already self-contained JSON (skill, source, version hash, verdict); opt-in sharing and aggregation is a v2.
• suggest-groups — scan installed skill descriptions and propose rival groups for your prefs.
• More hard adapters — as other CLIs grow pre-skill hooks.

License

MIT