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>
This commit is contained in:
29
plugins/kyberforge/skills/skill-audit/README.md
Normal file
29
plugins/kyberforge/skills/skill-audit/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# skill-audit
|
||||
|
||||
Audit a skill directory against the agentskills.io specification. Runs structural validation then a qualitative review across description quality, body discipline, formatting, file structure, and internal consistency.
|
||||
|
||||
## What it does
|
||||
|
||||
1. Runs `validate.sh` from `skill-write` for structural checks (name format, description length, line count, placeholder detection, script rules)
|
||||
2. Reads all files in the skill directory
|
||||
3. Applies qualitative checks across seven dimensions
|
||||
4. Outputs a PASS/FAIL/SUGGESTION punch list with a specific fix proposal for every FAIL
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/skill-audit
|
||||
```
|
||||
|
||||
Provide the path to the skill directory to audit when invoking.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `README.md` | This file |
|
||||
|
||||
## Dependencies
|
||||
|
||||
Requires `skill-write` to be installed at `plugins/kyberforge/skills/skill-write/` for the structural validation step. If not present, the agent performs structural checks manually.
|
||||
112
plugins/kyberforge/skills/skill-audit/SKILL.md
Normal file
112
plugins/kyberforge/skills/skill-audit/SKILL.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: skill-audit
|
||||
description: >
|
||||
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.
|
||||
allowed-tools: Bash Read
|
||||
metadata:
|
||||
category: factory
|
||||
---
|
||||
|
||||
## Step 1 — Structural validation
|
||||
|
||||
Locate the `validate.sh` script from `skill-write`:
|
||||
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user