Skip to content

Add the skill lifecycle hooks to the taxonomy table - #56

Merged
rocklambros merged 1 commit into
mainfrom
docs/hook-taxonomy-skill-hooks
Sep 8, 2026
Merged

Add the skill lifecycle hooks to the taxonomy table#56
rocklambros merged 1 commit into
mainfrom
docs/hook-taxonomy-skill-hooks

Conversation

@rocklambros

Copy link
Copy Markdown
Contributor

What changed

Specification section 5 listed sixteen hooks; the Hooks page lists nineteen. The gap is the entire skill lifecycle set (skillRegister, skillLoad, skillUnload), which reached the schemas, the Hooks page, conformance.md, and the skill AgBOM component type but never the taxonomy table. This adds the three hooks and renumbers the table to nineteen, then guards the set with a test.

Type of change

  • Specification change (schema, hooks, events, AgBOM)
  • Documentation
  • Tooling or CI
  • Governance (licensing, security policy, contributor docs)

Specification changes

No normative content changes. The three hooks were already normative in specification/v0.1.0/hooks/ and already documented on the Hooks page. This corrects a summary table that had drifted from them, and it deliberately does not restate the skill rationale, which stays on the Hooks page.

Breaking for implementers? No. Nothing on the wire changes. The practical effect is the reverse of breaking: implementers reading the specification page as canonical were never told skills are governable, so all three adapters in #22 emit no skill hooks at all.

Why it matters

skillRegister is the one point where a Guardian inspects a whole skill definition before any of its actions run. A payload split across a skill's actions is benign at each action and malicious only in composition, so per-action hooks cannot catch it. Omitting the set from the table people treat as the hook list quietly removed that gate from view.

The guard

tests/test_hook_taxonomy.py reads the title field of every schema under specification/v0.1.0/hooks/ as the normative source, then checks it against the section 5 table, the Hooks page overview table, and the hook count the Hooks page states, plus contiguous numbering.

Verified by injection rather than by inspection. Reverting the table fails with Specification section 5 omits hooks the schemas define: skillLoad, skillRegister, skillUnload; changing the stated count fails with Hooks page claims 16 native hooks; the schemas define 19.

This drift happened with a green build from start to finish, so only a check that reads the schemas prevents a repeat.

Not in scope

docs/acs.md carries the same defect ("16 native lifecycle hooks", skill hooks absent), but #21 already rewrites that exact line and names the skill hooks. Fixing it here would conflict with that PR for no gain. If #21 does not land, that line still needs the fix.

The skill hooks also have no OpenTelemetry span or OCSF class in specification/v0.1.0/trace/, so ACS-Trace cannot cover them today. That is a normative decision rather than a doc correction and is filed separately.

Checklist

  • Commits are signed off with git commit -s (required by the DCO)
  • Prose follows STYLE.md
  • uv run mkdocs build --strict passes
  • No secrets, tokens, or internal URLs in the diff

Full suite: 198 passed, 1 skipped.

Specification section 5 listed sixteen hooks. The Hooks page lists
nineteen. The gap is the skill lifecycle set: skillRegister, skillLoad,
and skillUnload reached the schemas, the Hooks page, conformance, and the
AgBOM component type, but never the taxonomy table.

The table is the summary a reader treats as the hook set, so the omission
taught anyone reading it that skills are not a governable surface. That is
the opposite of what the spec says: skillRegister is the one point where a
Guardian inspects a whole skill definition before its actions run, which
per-action hooks cannot cover.

List the three hooks in the order the Hooks page uses and renumber to
nineteen. Nothing here is new normative content; the rationale stays on
the Hooks page rather than being restated.

Guard the set against recurrence. The schemas' own titles are the
normative source, so the check reads them and compares against both
readable views plus the count the Hooks page states. The build stayed
green through the whole drift, so only a check that reads the schemas
catches it.

Signed-off-by: rocklambros <[email protected]>
@rocklambros rocklambros added the documentation Improvements or additions to documentation label Sep 8, 2026
@rocklambros
rocklambros merged commit 9d4a9da into main Sep 8, 2026
3 checks passed
@rocklambros
rocklambros deleted the docs/hook-taxonomy-skill-hooks branch September 8, 2026 02:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant