holocron/plugins/kyberforge/skills/skill-audit/SKILL.md

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
skill-audit	Use when the user wants to review a skill they wrote, says "audit this skill", "check if my skill follows best practices", "review my SKILL.md", or wants to know if a skill is ready to ship — even if they don't use the word "audit". Audits a skill directory against the agentskills.io specification — structural checks plus qualitative review of description quality, body discipline, formatting, file structure, and internal consistency. Produces a PASS/FAIL/SUGGESTION punch list with a specific fix proposal for every FAIL. Do not use to run evals, fix application code bugs, or perform general code review unrelated to skill quality.	Bash Read	category factory

Step 1 — Structural validation

bash scripts/validate.sh <skill-dir>

List every FAIL from the structural check in the punch list before continuing. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled FILL IN: placeholders, scripts executable and free of interactive prompts.

Step 2 — Read all skill files

Read every file in the skill directory: SKILL.md, README.md (if present), all files in scripts/, references/, and assets/. Skip binary files and files not directly referenced from SKILL.md. Do not skip text files — internal consistency checks require the full picture.

Step 3 — Qualitative audit

Work through each dimension. Cite file and line number for every finding.

Description

• Imperative phrasing: does it use "Use when..." not "This skill..."?
• Specificity: are capabilities stated precisely ("parses OpenAPI specs") or vaguely ("helps with APIs")?
• Indirect triggers: does it cover cases where the user doesn't name the domain directly?
• Near-miss exclusions: are "Do not use when..." clauses present if a near-miss skill could steal activations?
• Length: under 1024 characters?

If a description finding is borderline or the distinction between PASS and FAIL is unclear, read references/description-quality.md.

Body discipline

For each sentence in the body, apply: "Would the agent get this wrong without this sentence?" Flag any that answer "no" as padding.

• Defaults not menus: every decision point gives one default + one escape hatch, not a list of options
• Why rationale: include/exclude rules explain why, not just what
• Control calibration: prescriptive for fragile or critical sequences (e.g. a script invocation where flag order or exact arguments must not change); flexible where multiple approaches are valid

If uncertain whether a sentence is padding or whether a control decision is correctly calibrated, read references/body-discipline.md.

Patterns

Check each pattern is appropriate and correctly formed:

• Gotchas: placed near the top; each entry is a specific fact that defies a reasonable assumption — not a general tip
• Prescriptive sequence: inner code fences escaped as \``` when nested inside a markdown block
• Checklists: used for multi-step workflows, not single steps
• Conditional references: specific trigger stated ("If X, read references/file.md") — not a generic "see references/"
• Output templates: present when the agent must produce a specific format; absent otherwise

File structure

• Only spec-defined directories present: scripts/, references/, assets/
• No non-spec files (e.g. META.md, extra config files)
• Optional directories contain real content — not just unfilled placeholder READMEs
• README.md present and accurately describes the skill and its files
• No cross-plugin path references — paths using ../, ../../, or absolute repo paths (e.g. plugins/kyberforge/skills/...) break when the plugin is installed to a cache; flag any found

Formatting

• Heading levels consistent: H2 for main sections, H3 for subsections
• Code blocks fenced with a language tag where applicable (bash, markdown, python)
• Consistent whitespace: blank line between sections, consistent list indentation
• No broken relative paths in file references

Scripts

• No interactive TTY prompts (read, input(), readline)
• --help exposed with concise usage
• Data to stdout, diagnostics to stderr
• Idempotent ("create if not exists")
• Meaningful exit codes documented in --help
• --dry-run present for destructive operations

Internal consistency

• SKILL.md steps match what scripts actually do
• README.md file table lists every file that exists — no missing entries, no stale entries
• Placeholder READMEs in scripts/, references/, assets/ consistent with what SKILL.md says about each directory

Step 4 — Report

Output a punch list grouped by dimension:

PASS/FAIL/SUGGESTION  <finding> — <file>:<line>

Follow with a priority table:

Priority	Severity	Finding	File:Line

Then for each FAIL, a fix proposal:

FAIL: <finding>
Fix:  <exact change — quote before/after where applicable>

Do not apply fixes. Report and propose only.