# Skills Governance

How the ClawAI skills framework is maintained. Governance is itself a skill — if we don't govern, the framework rots.

## Ownership

Every skill file lists `owners` in its frontmatter. Default owners:

| Category                  | Owner             |
| ------------------------- | ----------------- |
| `foundations/`            | platform-team     |
| `backend/`                | platform-team     |
| `frontend/`               | frontend-team     |
| `security/`               | security-lead     |
| `testing/`                | qa-lead           |
| `e2e-manual-testing/`     | qa-lead           |
| `bulk-validation/`        | qa-lead           |
| `devops/`                 | platform-team     |
| `documentation/`          | tech-writing      |
| `workspace-integrations/` | integrations-team |
| `search-tool-use/`        | ai-platform-team  |
| `ollama-governance/`      | ai-platform-team  |
| `quality-gates/`          | platform-team     |

An owner listed in a skill is accountable for: review, accuracy, version bumps, and deprecation. Ownership can be individual or a team identifier.

## Lifecycle

```
draft → active → deprecated → archived
```

- **draft** — new skill, feedback-only, not yet enforced
- **active** — enforced; quality gates block merges if violated
- **deprecated** — still present but superseded; `replaced_by` set; 30-day grace
- **archived** — moved to `work/skills/.archive/` after grace period

## Changing a skill

### Patch change (typo, example, clarification)

1. Edit the file
2. Bump `version` patch (`1.0.3 → 1.0.4`)
3. Update `last_reviewed`
4. Open PR with label `skill:patch`
5. One owner review sufficient

### Minor change (add section, add rule, add example)

1. Edit the file
2. Bump `version` minor (`1.0.3 → 1.1.0`)
3. Update `last_reviewed`
4. PR label `skill:minor`
5. Two owner reviews required
6. Announce in `#engineering` Slack

### Major change (remove rule, change MUST/MUST NOT, change DoD)

1. Edit the file
2. Bump `version` major (`1.1.0 → 2.0.0`)
3. Update `last_reviewed`
4. Add `Migration notes` section describing the diff and reasoning
5. PR label `skill:major`
6. Two owner reviews + one security review (always, regardless of category)
7. Announce in `#engineering` Slack + link to PR
8. Active features in progress for 30+ days may opt into v1 via `skill-version-override.md`; new work uses v2

### Deprecation

1. Set `status: deprecated`
2. Set `replaced_by: <successor-id>`
3. Add banner to the top:
   ```markdown
   > **Deprecated 2026-04-19.** Replaced by [successor-id](successor-id.md). 30-day grace period ends 2026-05-19; file will be archived on that date.
   ```
4. Update `INDEX.md` to cross-reference both old and new for the grace period

### Archival

1. After grace period ends, move file to `work/skills/.archive/<category>/<skill-id>.md`
2. Remove from `INDEX.md`
3. Leave a one-line note in the archive about the final commit SHA of the removal

## Adding a new skill

1. Copy `templates/skill.template.md` to `work/skills/<category>/<new-id>.md`
2. Fill the frontmatter with `status: draft`
3. Write every mandatory section per `SKILL_FILE_SPEC.md`
4. Add entry to `INDEX.md` under the right category
5. Open PR with label `skill:new`
6. Collect feedback for at least 7 days (draft period)
7. Promote to `status: active` in a follow-up PR with `skill:promote`
8. Update `KPIS.md` if the skill introduces new measurable outcomes

## Quarterly review

Every skill with `last_reviewed` older than 90 days appears in the quarterly review list, auto-generated by `npm run skills:stale`.

At the review:

- Owner re-reads the skill in current repo context
- Updates examples to reference current code/files
- Bumps `last_reviewed` even if no content change
- Flags for deprecation if no longer applicable

## Validator

`scripts/validate-skills.mjs` runs in CI and locally (`npm run skills:validate`).

Validates:

- Frontmatter parses as valid YAML
- All required fields present
- `depends_on` resolves to existing files
- No circular dependencies
- `id` matches filename
- `version` is valid semver
- `last_reviewed` is an ISO date
- All mandatory sections present
- BLOCKER tokens are syntactically well-formed
- Link targets exist (relative paths)

Failure means PR blocked until fixed.

## How violations are detected

1. **PR-time** — reviewer checks the claimed-relevant skills and cross-references what was actually done.
2. **Commit-hook** — the commitlint config fails commits that claim "done" without evidence of the relevant quality gate.
3. **Release-gate** — the release checklist in `quality-gates/release-readiness-gate.md` requires evidence for each gate.
4. **Retro** — every incident retro asks: which skill would have prevented this? If no skill exists, one is proposed. If a skill existed but wasn't followed, that's a process failure.

## Conflict resolution

See `SKILL_FILE_SPEC.md` → "Conflict resolution". Persistent conflicts escalate to the category owners, then to the engineering leadership triad (platform, product, security).

## Contribution rules

- Changes to skills are public to the engineering org
- Skills are never private or team-restricted
- Skills describe **what must be done**, not **who does it**
- Pull-request comments pointing to skills are the norm — "this violates `backend/dto-design.md`"
- New hires are expected to read `foundations/` in onboarding week 1

## Success metrics

See `KPIS.md` for the quantitative framework. Qualitatively, the skills system is working when:

1. New engineers produce CLAUDE.md-compliant code in week 1
2. AI agents produce review-ready diffs on first attempt
3. Incident retros cite skills (either as prevention or as the gap)
4. Release blockers are caught pre-merge, not in staging
5. Documentation is never the reason a feature slips

## Anti-patterns

- Writing a skill that's just a link to a 10-page doc (useless — extract the rules)
- Writing "try to" instead of "MUST" (rules or delete it)
- Allowing drift between a skill and the code it describes (review quarterly)
- Letting skills accumulate without archival (stale skills teach bad habits)
- Treating the validator as optional (CI must fail on validation errors)
