Add the skill lifecycle hooks to the taxonomy table - #56
Merged
Conversation
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
requested review from
GangGreenTemperTatum,
afogel,
almogbhl,
bar-capsule,
fewdisc,
mamicidal,
sclintonowasp and
stefanoamorelli
as code owners
September 8, 2026 02:29
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 theskillAgBOM 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 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
skillRegisteris 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.pyreads thetitlefield of every schema underspecification/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 withHooks 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.mdcarries 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
git commit -s(required by the DCO)uv run mkdocs build --strictpassesFull suite: 198 passed, 1 skipped.