Fix allowed-tools to use spec-compliant space-delimited strings

[jonathanhefner]

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.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

All committers have signed the CLA.

[dguido]

Automated Review — PR #139

Warning: Complex PR — flagged for human review (touches CLAUDE.md)

Spec Verification

Confirmed against agentskills.io/specification: the allowed-tools field is defined as "A space-delimited list of tools that are pre-approved to run" with example allowed-tools: Bash(git:*) Bash(jq:*) Read. The YAML array format used previously was non-compliant. This PR correctly converts to the spec format.

Review Findings

All 23 SKILL.md files and CLAUDE.md are correctly converted. Changes are mechanical and consistent — each YAML list is flattened to a single space-delimited string on the same line as allowed-tools:.

Minor issues / observations:

1. firebase-apk-scanner uses comma-delimited format (allowed-tools: Bash({baseDir}/scanner.sh:*), Bash(apktool:*), Bash(curl:*), Read, Grep, Glob). This was pre-existing and not touched by the PR. The spec example uses spaces without commas (Bash(git:*) Bash(jq:*) Read), so the commas may be non-compliant. Could be fixed in a follow-up.

2. workflow-skill-design reference files still show YAML list format in code examples within references/anti-patterns.md (lines 261-308). These are illustrative examples inside a reference doc (not actual frontmatter), so it's debatable whether they need updating. Updating them would prevent contributors from copying the old format.

3. Commands and agents still use YAML list format (e.g., burpsuite-project-parser/commands/burp-search.md, zeroize-audit/agents/*.md, spec-to-code-compliance/commands/spec-compliance.md, skill-improver/commands/*.md). These are Claude Code plugin components, not agentskills.io skills, so they may follow a different spec. If the allowed-tools semantics are shared, these should also be converted. Worth confirming with the author.

4. Template example in workflow-skill-design SKILL.md line 127 wraps the placeholder in quotes: allowed-tools: "[minimum tools needed, space-delimited]". The quotes are technically valid YAML but could mislead contributors into thinking values need quoting. Nit-level.

Validation

• validate_codex_skills.py: PASS (61 skills, 62 Codex entries)
• validate_plugin_metadata.py: PASS (36 plugins)

Recommendation

Approve with optional follow-up for items 1-3 above. The core change is correct and well-scoped.

Changes Made

None — review-only for complex PRs.

---

Reviewed by Claude Code

[tob-joe]

From Claude (Joe asked me to analyze this; the text below is mine, not his):

Quick factual check on the "spec-compliant" framing. I verified against official docs and source code whether other agent implementations actually read the allowed-tools field, to see whether this PR improves real interop or is stylistic.

Summary of who reads allowed-tools from SKILL.md frontmatter:

Implementation	Reads the field?	Accepted format
Claude Code	Yes	"Accepts a space-separated string or a YAML list."
agentskills.io spec	Per spec	Space-separated string only; field marked "Experimental. Support for this field may vary between agent implementations"
OpenAI Codex CLI	No	N/A — uses a separate agents/openai.yaml with a dependencies.tools YAML list
Google Gemini CLI	No	N/A — frontmatter parser extracts only name and description

Source-code evidence that Codex and Gemini ignore allowed-tools entirely:

• Codex — the Rust frontmatter deserializer at codex-rs/core-skills/src/loader.rs defines SkillFrontmatter with only name, description, and metadata, and does not use deny_unknown_fields, so any allowed-tools value is silently dropped regardless of whether it's a list or a string. Tool dependencies are declared in a separate agents/openai.yaml file.
• Gemini CLI — the parser at packages/core/src/skills/skillLoader.ts returns exactly { name: string; description: string } | null. The built-in skill-creator/SKILL.md states: "name and description fields. These are the only fields that Gemini CLI reads..."

Implication:

The "non-compliant" framing is technically accurate against the agentskills.io spec but materially overstated. The field is flagged "Experimental" in that spec, and Claude Code — the only shipping runtime that actually parses allowed-tools — explicitly documents that it accepts both a YAML list and a space-separated string. Codex and Gemini CLI don't read the field at all, so this PR doesn't unlock any portability that didn't already exist.

The change is essentially stylistic: harmless, but not compliance work in any practical sense.

Also worth noting: this repo already uses several Claude-Code-only frontmatter fields (disable-model-invocation, argument-hint, context: fork, paths, etc.) that aren't in the agentskills.io spec, so strict spec compliance isn't currently the bar.

---

Note from Joe (separately): I'll check that this PR only makes the stated formatting changes and that the skills I have locally don't break if the allowed-tools section is reformatted that way. -Joe

[jonathanhefner]

Source-code evidence that Codex and Gemini ignore allowed-tools entirely:

• Codex — the Rust frontmatter deserializer at codex-rs/core-skills/src/loader.rs defines SkillFrontmatter with only name, description, and metadata, and does not use deny_unknown_fields, so any allowed-tools value is silently dropped regardless of whether it's a list or a string. Tool dependencies are declared in a separate agents/openai.yaml file.
• Gemini CLI — the parser at packages/core/src/skills/skillLoader.ts returns exactly { name: string; description: string } | null. The built-in skill-creator/SKILL.md states: "name and description fields. These are the only fields that Gemini CLI reads..."

That does not mean they will continue to ignore it in the future. Furthermore, those aren't the only agent clients.

The Agent Skills spec provides a baseline that agent clients can support. Yes, clients may support more than that baseline, but skills should target the baseline unless they have a good reason not to. I do not see a good reason to use a non-standard format for the allowed-tools field. Is there a reason I am missing?

[tob-joe]

yes, sorry if it was unclear -- I was checking whether this was an attempt to get buy-in for a standard being developed or if it was a flaw in the current skill repo that needed to be fixed for broader compatibility. Purely a question of urgency, not whether or not it should be fixed