Frontmatter Query
Use ${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query to query YAML frontmatter in markdown files. Do NOT parse frontmatter manually with grep, awk, or sed.
Subcommands
List all frontmatter
${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query list path/to/dir
${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query list path/to/file.md
Returns a JSON array of {path, ...metadata} for every .md file with frontmatter.
Search by key-value
${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query search path/ -k allowed-tools -v Bash
${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query search path/ -k tags -v python
Filters to files where the key matches the value. Matching is case-insensitive and supports list membership (e.g., a tags: [python, cli] field matches -v python).
Count tag values
${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query tags path/
${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query tags path/ -k allowed-tools
Returns {"value": count, ...} sorted by count descending. Defaults to the tags key; use -k to aggregate a different key.
Shared flags
| Flag | Effect |
|---|---|
--limit N | Return at most N results |
--body | Include markdown body in output |
--keys k1,k2 | Only include these frontmatter keys (plus path) |
Typical workflow
- Discover —
frontmatter-query list skills/to see all skill metadata - Filter —
frontmatter-query search skills/ -k allowed-tools -v Bashto find skills using Bash - Read — Use the
Readtool on specific files from the results
Exit codes
- 0: Success
- 1: Bad usage / invalid arguments
- 2: Path not found
Hook auto-approval
Commands using ${CLAUDE_PLUGIN_ROOT}/scripts/frontmatter-query can be auto-approved in Claude Code hooks. This is safe because the script is read-only (stdout output only, no disk writes).