# Skills Supply Chain Security

This document describes supply-chain controls for skill artifacts in this repository.

## Scope

Applies to skill files in `.github/skills/*/SKILL.md` and derived artifacts:
- `artifacts/skills-manifest.json`
- `artifacts/skills-manifest.sig.json`
- `artifacts/skills-sbom.cdx.json`

## Controls

1. Integrity manifest
- Generated by `scripts/generate-skills-manifest.js`
- Includes SHA-256 for each skill file

2. Signature metadata
- Generated by `scripts/sign-skills-manifest.js`
- Uses HMAC-SHA256 when `GH_SKILLS_SIGNING_KEY` is configured
- On `main`, signing is required in CI (`REQUIRE_SIGNING=true`)

3. SBOM generation
- Generated by `scripts/generate-skills-sbom.js`
- CycloneDX 1.5 JSON output

4. CI automation
- Workflow: `.github/workflows/skills-supply-chain.yml`
- Runs on skill/script changes and uploads artifacts

## Local Verification

Generate artifacts locally:

```powershell
node scripts/generate-skills-manifest.js
node scripts/generate-skills-sbom.js
node scripts/sign-skills-manifest.js
```

Check validator with Phase 3 options:

```powershell
node scripts/validate-agents.js --strict --validate-wcag --validate-urls --skip-url-checks
```

## Secret Management

Required secret for signing:
- `GH_SKILLS_SIGNING_KEY`

Recommendations:
- Rotate signing key on a defined cadence
- Restrict secret access to trusted workflows
- Require reviews for workflow changes

## Incident Response

If tampering is suspected:
1. Rotate `GH_SKILLS_SIGNING_KEY`
2. Regenerate manifest + SBOM + signature artifacts
3. Compare against last known-good artifacts
4. Investigate commit history and workflow run logs
5. Publish remediation notes in release documentation
