feat(skills): add canonical Akua agent skill artifact

[robinbraemer]

Intent

Correct existing CLI PR 20 so the public Akua agent skill has the canonical identity and source path skills/akua/SKILL.md while preserving its substantive guidance. Keep skill package metadata name and provenance canonical, recompute its deterministic digest, align Release Please wiring, and test exact directory/frontmatter/package identity plus rejection of task-shaped public names. The final PR must contain no retired internal task identity anywhere in tracked files or PR evidence. Keep changes limited to the skill source, metadata, focused tests, and necessary version wiring; do not add README or architecture documentation, modify distribution lanes or another repository, dispatch downstream sync, merge, publish, or tag. Update only existing PR 20 and validate focused tests, full checks, deterministic packaging, exact remote head, and CI green.

What Changed

• Add the canonical Akua agent skill with guidance for authoritative surfaces, structured CLI output, and approval-safe operations.
• Add deterministic skill package metadata with canonical identity, provenance, version, and content digest validation.
• Wire the skill package version into Release Please and document and test the artifact’s release contract.

Risk Assessment

✅ Low: The prior false-positive regression has been correctly fixed by validating a matching task-shaped name/path pair against the exact canonical akua identity, with no material collateral changes or remaining introduced risks found.

Testing

The prior remote-head mismatch is resolved: local HEAD, PR #20’s branch, and its successful CI run all identify 8724c6cdbcd586820d188da4ce54408d4b7b51d0. Focused and full tests passed, generated CLI artifacts were current, and two independently produced skill archives were byte-identical and contained only the canonical skill and metadata; extraction confirmed exact akua identity, CLI-owned provenance, release version, and matching deterministic digest. Local mise execution was blocked only by its worktree trust guard, so the identical generation command was run directly; static analysis was not run locally per instruction, while exact-target CI successfully ran the repository’s full mise run check.

Evidence: End-to-end skill package verification

Canonical Akua skill package — end-user verification

Archive contents:
akua/
akua/SKILL.md
akua/skill-package.json

Independent archive SHA-256 values:
864608d7ecbf3e2b730ac8441c5a758669728d27acdd80a75f8fe57c908dcc6e  /var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KXAM8NHZWV2ME5E54N0QQ6R4/akua-skill-a.tar
864608d7ecbf3e2b730ac8441c5a758669728d27acdd80a75f8fe57c908dcc6e  /var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KXAM8NHZWV2ME5E54N0QQ6R4/akua-skill-b.tar

Installed package identity and integrity:
{
  "directory": "akua",
  "frontmatter_name": "akua",
  "package_name": "akua",
  "package_version": "0.7.0",
  "provenance": {
    "repository": "https://github.com/akua-dev/cli",
    "path": "skills/akua/SKILL.md",
    "revision_source": "git"
  },
  "declared_skill_sha256": "01e1d7a7812ec3026419aebecfb27e54cbaff18c8386e9e50451f9af2a635979",
  "actual_skill_sha256": "01e1d7a7812ec3026419aebecfb27e54cbaff18c8386e9e50451f9af2a635979",
  "digest_matches": true
}

Retired public identity scan (expected: no matches):
no tracked-file matches

- Evidence: Deterministic canonical Akua skill archive (local file: /var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KXAM8NHZWV2ME5E54N0QQ6R4/akua-skill-a.tar)

Evidence: Exact remote head and successful CI evidence

Source: Exact remote head and successful CI evidence

PR #20 target and CI verification

Local target commit:
8724c6cdbcd586820d188da4ce54408d4b7b51d0

Remote PR branch head:
8724c6cdbcd586820d188da4ce54408d4b7b51d0	refs/heads/fm/akua-cli-skill-artifact

CI run filtered to exact target commit:
count: 1
runs[1]{id,title,status,conclusion,workflow,branch,event,created,sha,number,updated_at,url}:
  29184893862,"feat(skills): add canonical Akua agent skill artifact",completed,success,CI,fm/akua-cli-skill-artifact,pull_request,3m ago,8724c6cdbcd586820d188da4ce54408d4b7b51d0,106,3m ago,"https://github.com/akua-dev/cli/actions/runs/29184893862"
help[1]:
  Run `gh-axi run view <id>` to view details

PR checks summary:
summary: "1 passed, 0 failed, 1 total"
checks[1]{name,conclusion}:
  check,pass
help[2]:
  Run `gh-axi pr view 20` to see PR details
  Run `gh-axi pr merge 20` to merge when ready

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (8m50s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• ⚠️ test/agent-skill.test.ts:57 - This test does not independently reject task-shaped identities: it fails only because the fixture name differs from the fixed skills/akua parent directory. The same frontmatter would pass if validated at a matching task-shaped path. If task-shaped names must be prohibited, define that rule and test with a matching directory; otherwise rename this as another path/name drift case.

🔧 Fix: Enforce canonical Akua skill identity
✅ Re-checked - no issues remain.

🔧 **Test** - 1 issue found → auto-fixed ✅

• 🚨 PR feat(skills): add canonical Akua agent skill artifact #20 still points to commit 51a8662, not target 8724c6c. Its green CI check therefore does not validate the requested target; update the PR branch and rerun CI.
• bun test test/agent-skill.test.ts test/release-please-config.test.ts
• bun test
• mise run generate:check (blocked by untrusted worktree config; no user-level trust change made)
• bun run generate:check
• Created two git archive packages from HEAD:skills/akua, compared them byte-for-byte, extracted one, and verified installed frontmatter, package identity, provenance, version, and SHA-256
• Compared the initial artifact with the canonical rename and confirmed substantive guidance was unchanged apart from identity metadata
• Scanned tracked target files and PR #20’s body for the retired internal identity
• git ls-remote origin refs/heads/fm/akua-cli-skill-artifact refs/pull/20/head
• gh-axi pr checks 20
• git status --short

🔧 Fix: Update PR head and restore green validation
✅ Re-checked - no issues remain.

• git rev-parse HEAD and target diff/scope inspection against 634ad27d3c88b4df49a6959615208f80aca0ebb2
• bun test test/agent-skill.test.ts test/release-please-config.test.ts
• bun test
• mise run generate:check (blocked by untrusted isolated-worktree config), then equivalent bun run generate:check
• Created two packages using git archive --format=tar --prefix=akua/ … HEAD:skills/akua and compared their SHA-256 values
• Extracted the package and parsed SKILL.md frontmatter plus skill-package.json with bun -e; verified canonical identity, version, provenance, and matching content digest
• git grep -n 'agent-skills-standard-following' HEAD -- .
• git ls-remote origin refs/heads/fm/akua-cli-skill-artifact
• gh-axi pr view 20 --full and gh-axi pr checks 20
• gh-axi run list --workflow ci.yml --branch fm/akua-cli-skill-artifact --commit 8724c6cdbcd586820d188da4ce54408d4b7b51d0 …
• Final git status --short --untracked-files=all cleanup check

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.