g-skill-validate · diff
git:20260616.0256328 to git:20260722.4b86922
15 added, 16 removed. Audit A to A.
---
name: g-skill-validate
- description: Validate a skill or agent file against G-Forge structural rules. Checks SKILL.md format, command file, router registration, and agent frontmatter. Issues VALID or NEEDS FIXES verdict.
+ description: Validate a skill or agent file against G-Forge structural rules. Checks SKILL.md format, retired-shim absence, router registration, and agent frontmatter. Issues VALID or NEEDS FIXES verdict.
---
**Announce:** "Using g-skill-validate to validate the skill."
You are validating a G-Forge skill or agent against structural rules. Run all checks, produce a ✓/✗ checklist, and issue a final verdict.
## Step 1 — Identify what to validate
If a skill name was provided as an argument (e.g. the user typed `/g-skill-validate g-foo`), use that name.
If no argument was provided, ask:
> "Which skill or agent do you want to validate? Provide the skill name (e.g. `g-foo`) or agent filename (e.g. `code-reviewer.md`)."
Wait for input.
Determine from the name whether this is a skill (look for `skills/[name]/SKILL.md`) or an agent (look for `agents/[name]`).
## Step 2 — Validate SKILL.md (skills only)
Locate `skills/[name]/SKILL.md`. If the file does not exist, record: ✗ SKILL.md not found — skip remaining skill checks and go to Step 6.
Run these checks and record ✓ or ✗ for each:
**Frontmatter checks:**
- `name:` field present
- `description:` field present
+ - `context:` field (memory-layer declaration, G-RULES §J) is optional — its presence or absence is ✓ either way
- `argument-hint:` is NOT present (its presence is a violation — breaks skill loading)
+ - No frontmatter fields beyond `name`, `description`, and optionally `context` (any other field is a violation — flag it by name)
**Body checks:**
- `**Announce:**` line present (must appear before the first step)
- At least 2 numbered steps present (`## Step N —` format)
- `## Rules` section present
- No `Skill()` invocations anywhere in the file (search for `Skill(`)
- No hardcoded absolute paths starting with `/home/`, `/Users/`, `C:\`, `D:\` (use Glob to discover paths instead)
- ## Step 3 — Validate command file (skills only)
+ ## Step 3 — Validate shim absence (skills only)
- Locate `commands/[name].md`. If absent, record: ✗ command file missing.
+ Per ADR-007, `skills/[name]/SKILL.md` is the sole authored source for a skill — standalone `commands/[name].md` shims are retired.
- If present, check and record ✓ or ✗:
- - YAML frontmatter with `description:` present
- - File uses Glob+Read pattern to load SKILL.md (contains "Glob" and "SKILL.md")
- - No Skill() invocations (search for `Skill(`)
+ Check whether `commands/[name].md` exists:
+ - If it exists, record: ✗ retired shim present — `commands/[name].md` must be deleted (ADR-007: SKILL.md is the sole authored source; the shim produces a second, independently-drifting description surface).
+ - If it does not exist, record: ✓ no retired shim present.
## Step 4 — Validate router registration (skills only)
Read `commands/g-forge.md`. Check and record ✓ or ✗:
- - Subcommand name appears in the routing table (the `- \`[name]\`` lines)
- - Subcommand name appears in the description list at the bottom
+ - A bare-token routing line exists for this skill's subcommand (`- \`[token]\` → \`skills/g-[name]/SKILL.md\`` format)
+ - No per-skill prose or description accompanies that routing line or its subcommand token elsewhere in the router (the router carries bare tokens only — per-skill prose is a violation, ADR-007: it is the third description surface that drifted)
## Step 5 — Validate agent file (agents only)
If validating an agent, locate the agent file in `agents/`. If absent, record: ✗ agent file not found — skip to Step 6.
If present, check and record ✓ or ✗:
**Frontmatter checks:**
- `name:` field present
- `description:` field present
- `model:` field present (must be a model alias Claude Code accepts — `haiku`, `sonnet`, `opus`, or a newer top-tier alias such as `fable` — or a full `claude-*` model id. Warn rather than fail on an unrecognised bare alias: new model families ship ahead of this list)
- `tools:` field present
**Body checks:**
- Output Format section present (agents must define their report structure)
- Tools listed do not include Write, Edit, or Bash (agents are read-only)
- Body describes findings, not fixes (look for imperative "fix" language that shouldn't be there)
## Step 6 — Report
Output the full checklist, then issue the verdict:
```
## Skill Validation: [name]
### SKILL.md
✓ name: present
✓ description: present
✗ argument-hint: found on line 3 (must be removed — breaks skill loading)
✓ Announce line present
✓ Numbered steps (4 found)
✓ Rules section present
✗ Skill() invocation found on line 23 (remove — causes infinite loop)
✓ No hardcoded absolute paths
- ### Command file (commands/[name].md)
- ✓ description: in frontmatter
- ✓ Glob+Read pattern used
- ✓ No Skill() invocations
+ ### Shim absence (commands/[name].md)
+ ✓ no retired shim present
### Router (commands/g-forge.md)
- ✓ Routing table entry present
- ✗ Description list entry missing
+ ✓ Bare-token routing line present
+ ✗ Per-skill prose found alongside the subcommand token (must be removed — ADR-007)
---
VERDICT: NEEDS FIXES — 3 issues found
```
If all checks pass:
```
---
VERDICT: VALID — all checks passed
```
## Rules
- Run all checks before issuing the verdict — do not stop at the first failure.
- Never fix the issues yourself — report only. The developer fixes and re-runs validation.
- If the target file does not exist, the verdict is NEEDS FIXES with "file not found" as the finding.
- - For skills: validate SKILL.md + command file + router together — not just SKILL.md alone.
+ - For skills: validate SKILL.md + shim absence + router bare-token line together — not just SKILL.md alone (ADR-007: no per-skill command file; `commands/[name].md` existing is a violation, not a requirement).
- For agents: validate agent file only (no command file or router check needed).