dsh-skillnotary

A DSH plugin that pins what your agent's skills are allowed to do — and tells you when that changes.

An agent skill is a folder with a SKILL.md your agent loads and follows. It usually contains runnable shell, scripts and MCP config: unreviewed code with tool access, pinned to nothing, changing silently.

Most skill-security tools answer "is this skill dangerous right now?" skillnotary answers "is this still the skill I approved — and is it still only allowed to do what it did?" That is a different question, and it is the one that catches the change that happens after your review.

dsh plugin --profile web add github:liyixuan201211/dsh-skillnotary

中文：安装、更新、审查 agent skill 或 DSH 插件之前，先锁定它、审计它的能力，并在它被上游改动时发现。多数工具回答"这个 skill 现在危不危险"，本插件回答的是"它还是我批准的那个吗，还只被允许做当初那件事吗"。

---

What it changes

Once installed, the agent follows skills/skillnotary/SKILL.md: before adding or updating a skill it runs skillnotary audit (what can it do?), verify (is it what was approved?) and policy (is it allowed here?) — and reports a critical/high finding instead of quietly installing.

The moment it exists for:

$ skillnotary verify
✗ 2 drift(s) detected:
  ✗ release-notes [integrity-changed]    content digest changed: e4qHXFFicS -> Cj7IuwNp3Gb
  ✗ release-notes [capabilities-changed] capabilities changed: [exec] -> [agent.spawn,exec]

A hash tells you "something changed". That second line tells you the skill gained the ability to spawn further agents. Reproduce it yourself offline:

git clone https://github.com/liyixuan201211/skillnotary
cd skillnotary && bash demo/run.sh

Install

# this plugin
dsh plugin --profile web add github:liyixuan201211/dsh-skillnotary

# the tool it drives (not on npm yet; run it from git today)
npx --yes github:liyixuan201211/skillnotary --help

Pin the commit if you prefer:

dsh plugin --profile web add github:liyixuan201211/dsh-skillnotary#<commit>

This plugin ships no boot-time code

cordis.patch.yml is an empty patch, deliberately:

• a boot-time insert would run code inside the DSH process, for every profile, with your full privileges — a security plugin that widens the boot graph is itself attack surface;
• a bad insert can take down the whole boot layer (~/.dsh/cordis.patch.yml carries an explicit warning about this), and shipping something that could do it would be careless;
• the skill needs no privileges — it asks the agent to run npx skillnotary … through the normal shell tool, where you can see and approve each command.

So if you are reviewing this plugin before installing it: cordis.patch.yml is the whole story, and nothing there executes.

It audits itself

skills/skillnotary/SKILL.md is checked by skillnotary like any other skill, and it declares allowed-tools: Bash because it does ask the agent to run commands. That produces exactly one finding, and we left it in rather than gaming it:

MEDIUM   R007 Runtime package installation (SKILL.md:45)
         > npx --yes github:liyixuan201211/skillnotary --help

✓ no findings at or above "high"

npx is runtime package installation. Suppressing it would have been the dishonest move, and medium is below the default maxSeverity: high, so the CI gate still passes.

What skillnotary does, in one table

Pillar	Command	What you get
Lock	lock	skills.lock: content digest, resolved commit, and the capability set
Verify	verify	bytes and capabilities drifting from what you approved
Attest	keygen / sign	ed25519 over a DSSE envelope with an in-toto statement
Govern	policy	per-skill allow/deny, per-capability gates, severity threshold
Repair	fix	write the allowed-tools a skill actually needs into its SKILL.md
Install	apply	copy locked skills into a harness dir, re-checking every digest
Gate	ci	all of the above as one CI step

Zero runtime dependencies; TypeScript with no build step (Node ≥ 23.6).

Honest limits

• Detection is context-scoped regex, not a sandbox. Targeted obfuscation evades it; a clean report means "no known signals", not "safe".
• Only the head of each file is scanned (1 MB per file, 64 MB per skill); rule R025 says so when that truncates instead of hiding it.
• Attestations are DSSE + in-toto, but this is not Sigstore — no keyless/OIDC, no transparency log.
• The lockfile pins a skill; it does not sandbox what the skill does when your agent runs it.

Links

• skillnotary — the tool: https://github.com/liyixuan201211/skillnotary
• Security audit of the tool itself (8 findings, all fixed): https://github.com/liyixuan201211/skillnotary/blob/main/SECURITY-AUDIT.md
• Plugin marketplace: https://awesome-dsh-plugin.com

Licence

MIT