OpenSkillIndex← back to search
claude-code

GAAI-framework skill-usage-audit

Scan all artefacts (epics, stories, PRDs) for Base Rule #2 compliance — verify that every artefact declares skills_invoked and related_decs in frontmatter. Produces an audit report with pass/fail per artefact and overall compliance rate.

install
source · Clone the upstream repo
git clone https://github.com/Fr-e-d/GAAI-framework
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/Fr-e-d/GAAI-framework "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.gaai/core/skills/cross/skill-usage-audit" ~/.claude/skills/fr-e-d-gaai-framework-skill-usage-audit && rm -rf "$T"
manifest: .gaai/core/skills/cross/skill-usage-audit/SKILL.md
source content

Skill Usage Audit

Purpose / When to Activate

Activate:

  • Periodically (e.g., after a Discovery session) to verify governance compliance
  • Before a release or milestone to audit artefact quality
  • When trust in agent compliance needs verification
  • On demand by the human (
    /gaai-status
    or direct invocation)

This skill enforces Base Rule #2 (Skill-first) by scanning artefacts for the 

skills_invoked
attestation field. It detects artefacts that were produced from cached knowledge without reading the corresponding skill file.

Process

  1. Scan all Epic files at 

    contexts/artefacts/epics/*.epic.md
    (exclude 
    _template.epic.md
    ):

    • Check frontmatter for 
      skills_invoked
      field
    • If present: verify it includes 
      generate-epics
    • If missing: mark as FAIL

  2. Scan all Story files at 

    contexts/artefacts/stories/*.story.md
    (exclude 
    _template.story.md
    ):

    • Check frontmatter for 
      skills_invoked
      field
    • If present: verify it includes 
      generate-stories
    • If missing: mark as FAIL
    • Check frontmatter for 
      related_decs
      field
    • If missing: mark as FAIL (separate from skills_invoked)
    • Check frontmatter for 
      epic
      field
    • If missing: mark as WARN

  3. Produce audit report with:

    • Per-artefact pass/fail status
    • Compliance rate: 
      (passing artefacts / total artefacts) × 100
    • List of non-compliant artefacts for remediation
    • Timestamp of audit

Outputs

Skill Usage Audit Report — {date}

Epics scanned: {count}
Stories scanned: {count}

Non-compliant artefacts:
- {id}: FAIL — missing skills_invoked
- {id}: FAIL — missing related_decs
- {id}: WARN — missing epic field

Compliance rate: {n}/{total} ({pct}%)

Verdict: CLEAN | {n} VIOLATIONS FOUND

Remediation

For each non-compliant artefact, the human or agent must:

  1. Read the corresponding skill file (
    generate-stories/SKILL.md
    or 
    generate-epics/SKILL.md
    )
  2. Verify the artefact content follows all process steps
  3. Add the missing frontmatter fields
  4. Commit the fix

This skill does NOT auto-fix artefacts — it reports only. Remediation is a conscious act.

Quality Checks

  • Every artefact file in the scan directories is checked (no silent skips)
  • Template files (
    _template.*
    ) are excluded from the scan
  • The report clearly distinguishes FAIL (blocking) from WARN (advisory)
  • Compliance rate is computed correctly

Non-Goals

This skill must NOT:

  • Auto-fix artefacts (report only — remediation is deliberate)
  • Check artefact content quality (use 
    validate-artefacts
    for that)
  • Scan non-artefact files (memory, decisions, patterns)