* Give differential-review a trigger, and name every component in its README
differential-review's description listed what it does and never named a
situation, so it competed on capability wording alone. It now closes with
the triggers its own README already documents — reviewing a PR, commit,
or diff; checking whether a change re-introduces a fixed bug; asking what
else a change could break; finding modified code with no test.
The same plugin's README never mentioned adversarial-modeler, which is
what Phase 5 dispatches for HIGH RISK changes. Checking whether that was
isolated turned up more of it, and the sweep found three kinds of gap:
zeroize-audit's agent table was missing three of its eleven agents —
0-preflight, which gates the entire run, plus 5b-poc-validator and
5c-poc-verifier. All three appear in the phase diagram directly above the
table, which is why they read as present.
constant-time-analysis documents the ct-analyzer CLI end to end and never
says the plugin also ships a skill and a command. entry-point-analyzer
lists phrases that trigger its skill but never names the skill or its
command.
Three more READMEs describe their skill without naming it. That matters
most where the skill name is not the plugin name and a user cannot guess
it: chrome-mcp-troubleshooting and interpreting-culture-index.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Fix review findings and make the README sweep a gate
The two PoC rows I added to zeroize-audit said Phase 4. The diagram three
lines above them, SKILL.md, and workflows/phase-5-poc-validation.md all
say Phase 5, steps 5a and 5b. "Wave 5a" is a label that exists nowhere.
A debugger consulting the table — the artifact this branch designates as
what runs when — would have opened phase-4-poc-generation.md and found no
validation in it. Also corrected the sentence introducing that table,
which still said 10 agents across 8 phases against 11 across 9, and the
Phase 0 diagram line, which still credited the orchestrator for a gate
the new row credits to 0-preflight.
differential-review's README claimed the agent is "dispatched", and named
it bare in a column whose other rows are namespaced. Nothing dispatches
it: the only instruction is prose in SKILL.md, and a bare subagent_type
fails at runtime. Namespaced both, and corrected the five stale line
counts in the same file — reporting.md is 369 lines, not the ~120 the
token-efficiency section budgets for.
Drop the dead `name: trailofbits:<cmd>` key from five command files.
The three newest command files carry no name: at all, #275 namespaced 22
bare invocations, and this branch documents the `/<plugin>:<cmd>` form —
so the key contradicts the docs it sits next to.
Then make the sweep repeatable. Doing this by hand three times found
eight gaps and missed two more, both of the same shape: a workflow ships
under meta.name, not its filename, so a README citing the filename never
writes the name a reader types. The validator now checks that a README
names every skill, agent, command, and workflow its plugin ships, reading
meta.name for workflows. It refuses a run that inspected zero components,
and six self-test assertions hold it to known-bad fixtures.
It found git-cleanup on its first run: ships as /git-cleanup:git-cleanup-analysis,
README cites workflows/analyze-branches.js four times and that name never.
static-analysis had the same gap for codeql-build.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Fix both P2s: the gate was a substring test, and the dispatch was still bare
The README gate ran `name not in text`. That reads as thorough and could
not fail for a large share of what it counted: `draw` was satisfied by
"(draw cards instead)", `semgrep-rule` by the plugin's own name in the
install line, `burp-search` by a `scripts/burp-search.sh` path that is a
different thing, and `audit` by the prose "shared-state struct audit".
Match by kind instead. Commands and workflows are reachable only as
`/<plugin>:<name>`, so require that literal — it is the only string a
user can type. Agents are dispatched by identifier and never typed as
prose, so require an identifier-shaped mention. Skills are genuinely
referred to by bare name, so require only a delimited occurrence, which
is what stops "draws" counting as `draw`.
That surfaced seven real gaps, the four above plus insecure-defaults'
audit-pipeline workflow, mutation-testing's skill, and trailmark's
code-slice-worker. All seven fixed.
adversarial-modeler was still bare at SKILL.md:96. Line 77 was the
decision-tree mention; line 96 is the "Delegate to this agent"
instruction a model actually acts on, so the runtime failure the last
commit claimed to fix survived it. Namespaced, and it now says why.
Also from the review: a per-kind floor, since a single total stays
healthy while skill_files() — 63% of coverage — silently stops matching;
workflow_names anchored to the meta block, because a bare search takes
any earlier `name:` in a comment, and .mjs was invisible; and AGENTS.md
documents the new hard failure. Self-test 88 -> 96, each new rule with a
negative control.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* feat(codex): add skill UI metadata
* Use official Trail of Bits logo
* fix: resolve code review findings for PR #175
Codex silently drops the icons as authored: its loader
(codex-rs/core-skills resolve_asset_path) requires icon paths
containing '..' to resolve under <plugin_root>/assets/, and the
repo-root .codex/assets location fails that containment check.
Verified empirically via codex app-server plugin/read: every
iconSmall/iconLarge came back null; only brand_color applied.
P1 fixed:
- Vendor trail-of-bits-mark.svg into plugins/<name>/assets/ for
all 38 plugins with skills and point every openai.yaml at
../../assets/trail-of-bits-mark.svg (the supported plugin-level
shared asset pattern). Icons now resolve for marketplace
installs too, since nothing escapes the plugin root.
- Drop the .codex/ additions: .codex/skills/gh-cli/agents/
openai.yaml resolved nowhere (.codex/skills is not a Codex
discovery root) and PR #173 removes the whole .codex/ tree
P2 fixed:
- Patch-bump all 38 touched plugins in plugin.json and
marketplace.json so installed clients pick up the metadata
Verified:
- Static check replicating Codex's resolution algorithm: all 73
yaml files resolve under their plugin assets/ and exist
- Live codex app-server probe: 71/72 loadable skills report
resolved iconSmall/iconLarge and brand_color #D83A34
(claude-in-chrome-troubleshooting fails to load on main due to
a pre-existing 64-char qualified-name limit, fixed by #173's
rename; zeroize-audit's manifest mcpServers object is likewise
a pre-existing Codex incompatibility fixed by #173)
- validate_codex_skills.py, validate_plugin_metadata.py, prek all
pass
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(codex): use skill-local icon assets
---------
Co-authored-by: Dan Guido <dan@trailofbits.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Fix `allowed-tools` to use spec-compliant space-delimited strings
Per the agentskills.io specification, `allowed-tools` must be a single
string of space-delimited patterns, not a YAML list. Converted all 23
SKILL.md files from the `- Item` list format to the correct
`"Item1 Item2"` string format. Also updated the frontmatter examples in
CLAUDE.md and the workflow-skill-design skill template to match.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Fix remaining allowed-tools format in firebase-apk-scanner and workflow-skill-design docs
- Convert firebase-apk-scanner from comma-separated to space-delimited
- Update anti-patterns.md and tool-assignment-guide.md examples from YAML lists to space-delimited strings
- Remove unnecessary quotes from SKILL.md template placeholder
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Cover commands, new SKILL.md files, and fix template placeholder
Extends the previous spec-compliance fixes:
* Convert command frontmatter (commands/*.md) — per Claude Code
docs, command files use the same frontmatter as skills, so the
same space-delimited rule applies.
* Convert three SKILL.md files added since the original PR:
mutation-testing, trailmark-structural, trailmark-summary.
* Fix the placeholder in the workflow-skill-design template.
The previous "[minimum tools needed, space-delimited]" was YAML
flow-sequence syntax, which parses as a list — the opposite of
what the placeholder claims. Replaced with a concrete-looking
space-delimited example plus a comment.
Zeroize-audit agent files still use `allowed-tools:` in YAML list
form. They are intentionally excluded: per the project's own docs
(workflow-skill-design references), agents declare tools with
`tools:` (not `allowed-tools:`). Fixing those requires changing
the field name as well as the format and is out of scope for this
PR.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* zeroize-audit agents: switch allowed-tools to tools
Subagents declare their tool allowlist via `tools:` (comma-separated),
not `allowed-tools:` — see Claude Code's subagent docs and this
repo's own designing-workflow-skills/SKILL.md:47:
> Skills use `allowed-tools:` in frontmatter. Agents use `tools:`
> in frontmatter.
Before this change, the zeroize-audit agents declared their tool list
under `allowed-tools:`, which Claude Code does not read for subagents.
The field was effectively a no-op; the spawned agents had no tool
restriction enforced.
Renames the field on all 11 agents to `tools:` and reformats the YAML
list as comma-separated to match the documented format and existing
agents elsewhere in the repo (e.g. function-analyzer.md,
spec-compliance-checker.md). Tool sets are unchanged.
Behavior change: tools now actually constrain what each spawned agent
can call. The lists are the ones the original author intended.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* skill-improver: convert command allowed-tools to space-delimited
The two command files in plugins/skill-improver/commands/ still used
the JSON flow-array format (`allowed-tools: ["..."]`), which the rest
of this PR converted everywhere else. Convert them to the spec-compliant
space-delimited string form for consistency.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Dan Guido <dan@trailofbits.com>
Pre-commit hooks auto-fixed missing newlines at EOF and trailing
whitespace to satisfy end-of-file-fixer and trailing-whitespace checks.
Co-authored-by: Dallas McIntyre <dkmcintyre@safaricircuits.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
Rename 10 command files that contained `:` in their filenames, which is
invalid on Windows filesystems (reserved for drive letters).
The `trailofbits:` namespace is preserved in the frontmatter `name` field,
so slash commands like `/trailofbits:audit-context` continue to work.
Fixes#51
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- Split into separate refs for Sui and Aptos (since both the syntax and semantics are pretty different). Tweak SKILL.md to detect the correct file type
- Make the Sui ref more accurate--old one would skip all `public` but non-`entry` functions, which is a substantial part of the attack surface
kz-tob