holocron/plugins/kyberforge/skills/skill-audit/SKILL.md at 6317b5c844d00a0c7fb9d818766c47ab863e4540

Files

Defame1297 672fd25890 feat(kyberforge): replace write-skill with spec-compliant skill-write and add skill-audit

Rewrote the skill authoring factory skill from scratch against the agentskills.io
specification. Renamed write-skill → skill-write (name now matches directory per spec).

skill-write:
- Full scaffold via new-skill.sh (annotated templates for SKILL.md, README.md,
  scripts/, references/, assets/)
- validate.sh checks all spec constraints deterministically (name format/length,
  description length, placeholder detection, line count, script rules)
- SKILL.md body includes description rules, body discipline, patterns, and scripts
  guidance with "why" rationale throughout
- Templates usable standalone by agents and humans

skill-audit:
- Structural validation (via validate.sh) + seven qualitative dimensions
- Produces PASS/FAIL/SUGGESTION punch list with per-FAIL fix proposals
- Report-only: does not apply fixes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-22 18:50:00 +00:00

4.5 KiB

Raw Blame History

name, description, allowed-tools, metadata

name

description

allowed-tools

metadata

skill-audit

Audit 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. 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". 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

Locate the validate.sh script from skill-write:

bash plugins/kyberforge/skills/skill-write/scripts/validate.sh <skill-dir>

If validate.sh is not found, note it and proceed — perform the checks it would cover manually.

List every FAIL from the structural check in the punch list before continuing.

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/. Do not skip 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?

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; flexible where multiple approaches are valid

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

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.

4.5 KiB Raw Blame History