[Docs] Skill lifecycle hooks have no ACS-Trace mapping (no OTel span, no OCSF class)

[rocklambros]

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:

• 6002 Application Activity, treating a skill load as application behavior, consistent with agentTrigger and turnStart.
• 5001 Inventory Info, treating registration as a component entering the inventory, consistent with agbom/snapshot and with the fact that a registered skill becomes a skill AgBOM component.
• Split them: skillRegister as 5001 because it is an inventory event that adds a component, and skillLoad / skillUnload as 6002 because 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.

[sabasiddique1]

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 as acs.skill / acs.skill.end the way subagent does, for two reasons: unload is optional (a loaded skill can simply live until sessionEnd), 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 by acs.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 persists definition.ref/digest to the AgBOM), and skillLoad → 1007 Process Activity rather than 6002, because a digest-verified load into execution is closer to toolCallRequest than to turnStart. 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.id is required on all three; acs.skill.digest on register and load (the schemas require it there, unload carries only reason). load_path is a required attribute on acs.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 — and events.md already says provenance lineage MAY be linked via span links keyed by provenance_id, so a SHOULD for load_path links 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.md already 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.