Repository navigation
[Docs] Skill lifecycle hooks have no ACS-Trace mapping (no OTel span, no OCSF class) #57
Description
Summary
The skill lifecycle hooks (skillRegister, skillLoad, skillUnload) have no OpenTelemetry span name and no OCSF event class. They are absent from both normative mapping files and from both tables on the Trace page. A deployment that emits them cannot claim ACS-Trace for them, because there is nothing to map them to.
Evidence
$ grep -c skill specification/v0.1.0/trace/otel-mapping.json
0
$ grep -c skill specification/v0.1.0/trace/ocsf-mapping.json
0
docs/spec/trace/events.md omits them from both the OTel span table and the OCSF class table. docs/spec/trace/extend_ocsf.md omits them as well. Every other native steps/* hook appears in all of these.
Why this is not just a documentation gap
The three hooks are normative in specification/v0.1.0/hooks/ and are listed in conformance.md as SHOULD-implement. The AgBOM already carries a skill component type. So a conformant deployment can be told to emit skill hooks and to claim ACS-Trace, and then find the two requirements do not compose.
This blocks implementers concretely. The three adapters in #22 emit no skill hooks today; if that is addressed, the emitted steps have no trace representation.
Same root cause as #56
The taxonomy table in Specification section 5 listed sixteen hooks while the Hooks page listed nineteen, omitting exactly this set. #56 fixes the table and adds a guard that binds it to the schemas. The Trace mappings were missed by the same original omission, but closing them requires decisions rather than a correction, so they are split out here.
Note that #56's guard covers the Instrument tables only. It does not check the Trace mappings, so it will not catch this or prevent a repeat. Worth extending once the mappings exist.
Decisions needed
OTel span names. The existing convention is acs.<area> with .end or a verb suffix (acs.subagent / acs.subagent.end, acs.compact / acs.compact.complete, acs.memory.store). Candidates: acs.skill.register, acs.skill.load, acs.skill.unload. Open question whether load and unload should pair as a span and its end, the way acs.subagent does, since a loaded skill has a lifetime within the session rather than being a point event.
OCSF class. Not obvious, and the choice carries meaning for SIEM consumers:
6002Application Activity, treating a skill load as application behavior, consistent withagentTriggerandturnStart.5001Inventory Info, treating registration as a component entering the inventory, consistent withagbom/snapshotand with the fact that a registered skill becomes askillAgBOM component.- Split them:
skillRegisteras5001because it is an inventory event that adds a component, andskillLoad/skillUnloadas6002because they are runtime activity.
The split reads most faithful to what the hooks actually do, but it is the least consistent with how the other pairs were mapped, so it needs an owner's call.
Attributes. At minimum acs.skill.id and the digest. Whether the digest goes on the span as an attribute, and whether load_path is represented as an attribute, a span link, or parent/child spans, is worth deciding deliberately, since load_path is the inter-skill cascade signal and span links would preserve it better than a flattened string.
Scope
Touches specification/v0.1.0/trace/otel-mapping.json, specification/v0.1.0/trace/ocsf-mapping.json, docs/spec/trace/events.md, and docs/spec/trace/extend_ocsf.md. Whether this lands in v0.1.0 as a gap-fill or waits for v0.2 is part of the decision.
Activity
sabasiddique1 commentedon Sep 9, 2026
PR #63 covers the mapping side of this as well as #58 — I found #58 first and #57 only after opening the PR, apologies for the split attention. Happy to break #63 into two stacked PRs (mappings first, then the guard, since the guard can't go green until the mappings exist) if you'd rather review the decisions separately. Taking your open questions in order:
Span names.
acs.skill.register/acs.skill.load/acs.skill.unload, as point events. I didn't pair load/unload asacs.skill/acs.skill.endthe way subagent does, for two reasons: unload is optional (a loaded skill can simply live untilsessionEnd), so a span that may never close is awkward; and the cascade signal sits on load, not on the lifetime. Correlation across the three is byacs.skill.id. If you'd rather have the span/end pair, it's a rename.OCSF class. I took the split you called most faithful, with one change:
skillRegister/skillUnload→ 5001 Inventory Info (component enters or leaves the set; the register schema persistsdefinition.ref/digestto the AgBOM), andskillLoad→ 1007 Process Activity rather than 6002, because a digest-verified load into execution is closer totoolCallRequestthan toturnStart. 1005 Module Activity (Load=1 / Unload=2) is the closest OCSF semantic for load/unload but introduces a class the mapping doesn't use today. Your call — the JSON_notes state the reasoning either way.Attributes /
load_path.acs.skill.idis required on all three;acs.skill.digeston register and load (the schemas require it there, unload carries onlyreason).load_pathis a required attribute onacs.skill.load(array of skill ids, root first) so the cascade is always present on the event. For lineage I'd rather add span links than parent/child spans, because loads can be triggered outside any open skill span — andevents.mdalready says provenance lineage MAY be linked via span links keyed byprovenance_id, so a SHOULD forload_pathlinks follows the same pattern. Not in #63 yet; one line if you want it.v0.1.0 vs v0.2. I treated it as a v0.1.0 gap-fill: the hooks are already normative in v0.1.0 and
conformance.mdalready says SHOULD, so a deployment can be told to emit them today. Deferring the mapping to v0.2 leaves that non-composable for a release cycle.Also: the guard from #56 is extended in #63 to cover the Trace mappings and every other surface that restates the set, which is the "worth extending once the mappings exist" note here.
[-]Skill lifecycle hooks have no ACS-Trace mapping (no OTel span, no OCSF class)[/-][+][Docs] Skill lifecycle hooks have no ACS-Trace mapping (no OTel span, no OCSF class)[/+]Add the skill lifecycle hooks to the Trace mappings (GenAI-Security-P…