Session-Triage Handoff Contract

session-triage verifies one incident and recommends a durable fix. Its output routes the fix to implementation via one of two branches, decided by where the defect lives. There is no skill-builder skill in this route — targeted-skill-builder and create-agentic-skill are archived, and the managing-layer handoff payload below is the implementation route.

Branch selection

Classify the verified defect before writing the handoff:

• Managing-layer defect — the fault is in a shared skill contract, a convention page (docs/*-convention.md, CLAUDE.md, shared process/routing docs), or workflow routing/process. The fix belongs in the managing agentic-skills repo and must reach every install. → emit the managing-layer handoff payload (YAML).
• Invoking-directory defect (rare) — the fault is in the current/consuming project itself (its own code, local config, or project instructions), not in a shared skill/convention/process. The fix belongs in that directory. → emit a plain in-place patch report (no YAML payload, no managing-repo route).

When in doubt between the two, prefer managing-layer only when the fix would change a shared skill/convention/process file under the agentic-skills repo; otherwise the fix is invoking-directory.

Managing-layer handoff payload

A self-contained YAML block any agent running in the agentic-skills repo can execute directly. It carries the canonical target, the exact fix, the publish + refresh loop, and verification — so the fix reaches the canonical source and every install without a builder skill.

# Invoke with: run this in the agentic-skills repo to implement + publish the fix
command: "implement-skill-fix"        # descriptive; not a skill command
defect_class: skill | convention | routing-process
target:                               # canonical source-of-truth only
  - packs/<pack>/claude/<skill>/SKILL.md
  - packs/<pack>/codex/<skill>/SKILL.md
fix: |
  <exact rule text / section change>
publish_refresh:
  - scripts/skill-archive.sh <skill-dir>; bump version; update CHANGELOG
  - git add <edits>; npm run skillpacks:build; git add manifest; commit together; push
  - scripts/pack.sh refresh
verify:
  - <rg checks / mirror version check / failing test or log cmd>

Field rules

• command — a human/LLM attention cue only; descriptive, not a slash/$ skill command. Parsers must not depend on the leading # Invoke with: comment.
• defect_class — one of skill, convention, routing-process.
• target — the canonical source-of-truth only:
• Skill: packs/<pack>/{claude,codex}/<skill>/SKILL.md. Resolve <pack> with scripts/pack.sh which <skill>. Fall back to legacy base/{claude,codex}/<skill> only if the skill has not migrated to packs/. List both claude and codex variants when both exist.
• Convention / process: the authoring source under docs/ (e.g. docs/*-convention.md) or CLAUDE.md.
• Never a managed mirror or installed copy: .claude/skills/…, .codex/skills/…, ~/.claude/skills/…, ~/.codex/skills/…, ~/.npm/**/skillpacks/…, packages/skillpacks/build/…, or a generated per-skill bundle (ALIGNMENT-PAGE.md, INTERROGATION-PAGE.md). Those are read-only evidence; a patch to one does not propagate.
• fix — the exact rule text / section change, concrete enough to apply without re-deriving the diagnosis.
• publish_refresh — the full loop, in order: archive + version bump + CHANGELOG per CLAUDE.md skill-versioning → update both variants → git add edits → npm run skillpacks:build (regenerates the index-sourced packages/skillpacks/dist/skillpacks-manifest.json) → git add the manifest → commit source + manifest together → push → scripts/pack.sh refresh in-repo (consumers run npx skillpacks install/refresh + /reload-skills, or a fresh Codex CLI session). A managing-layer fix is not complete until published and refreshed. The managed mirrors are gitignored and regenerated by refresh — never hand-edit them.
• verify — the checks that prove the revised behavior prevents the issue (targeted rg, mirrored-contract check, version check, refreshed-mirror version check, or the failing test/log command).

Cross-directory rule

When session-triage runs from a consuming or other directory (cwd is not the managing agentic-skills repo), a managing-layer fix still routes back to the managing repo via the payload — the local installed copy in the current directory is not edited as the fix. If the managing repo is not checked out locally, say so and stop rather than patching a mirror.

Invoking-directory report

For an invoking-directory defect, emit a plain report (no YAML command, no managing-repo route):

• Defect and root cause, scoped to the current directory.
• Exact file(s) in the current directory to change, with the concrete change.
• Local verification (test/build/log command run from that directory).