# Skill Usage Audit

> Scan all artefacts (epics, stories, PRDs) for Base Rule

- Skill: `aibot88/skill-usage-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aibot88/skill-usage-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aibot88/skill-usage-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: ELv2
- Author: aibot88 (https://skillmd.com/u/aibot88)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/aibot88/skill-usage-audit

---


# 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)