RFC: metadata.activation — normalized hook lifecycle events for portable skill declarations

[unional]

Summary

Proposal to document a recommended metadata.activation key: normalized kebab-case hook lifecycle event names that skill authors can declare in SKILL.md frontmatter, with a mapping table to host-specific hook config keys (Claude Code, Cursor, Codex).

This is Phase 1 metadata convention work — not hook payload formats, not matchers, not requiring every host to implement every event yet.

AI disclosure: Draft prepared with AI assistance from a reference implementation in cyber-skills (governance show skill-design, activation research doc). A human reviewer should validate host mappings before spec adoption.

Problem

The Agent Skills spec defines optional metadata for author/client extensions, but there is no portable vocabulary for declaring which agent hook lifecycle event should run a skill.

Hosts use incompatible config key names today:

Normalized (proposed)	Claude Code	Cursor	Codex
session-start	SessionStart	sessionStart	SessionStart
post-tool-use	PostToolUse	postToolUse	PostToolUse
pre-tool-use	PreToolUse	preToolUse	—
after-file-edit	—	afterFileEdit	—

Skill authors currently duplicate host-specific hook registration knowledge in prose, READMEs, or tool-specific sidecars — which breaks portability.

Related but distinct threads

• #57 RFC: Skill Activation Mechanisms — broader question of when agents should load/follow skills (signals, priority, agent contract). Valuable, but orthogonal to hook event name normalization.
• Discussion #152 — sub-agents, skills, hooks, rules interoperability — packaging and linking model; this RFC is a concrete metadata key that hooks into that direction.
• #271 includes frontmatter — multi-skill repo bundling; complementary extended-frontmatter work.

I searched Issues/Discussions for metadata.activation, hook lifecycle normalization, and session-start/post-tool-use metadata conventions and did not find an equivalent proposal.

Proposal

Add a metadata conventions appendix (or companion doc) documenting:

metadata:
  activation: session-start   # or per-situation, post-tool-use, …

Allowed values (registry excerpt)

metadata.activation	Role
per-situation	Default. No hook; load via description / explicit invoke
session-start	Chat/session opens or resumes
session-end	Session ends
pre-tool-use	Before any tool call
post-tool-use	After tool succeeds
post-tool-use-failure	After tool fails
before-submit-prompt	Before prompt sent
before-shell-execution / after-shell-execution	Shell command lifecycle
before-mcp-execution / after-mcp-execution	MCP call lifecycle
before-read-file / after-file-edit	File read/edit lifecycle
subagent-start / subagent-stop	Subagent lifecycle
pre-compact	Before context compaction
stop	Agent turn completes
after-agent-response / after-agent-thought	Response/thought lifecycle
before-tab-file-read / after-tab-file-edit	Tab completion lifecycle

Full host mapping table (Claude / Cursor / Codex equivalents, including — where no documented equivalent) is in the reference doc below.

Authoring rules

1. Default: omit key or set per-situation — no hook registration implied.
2. Hook-backed skills: set metadata.activation to the normalized event; hosts/tooling map to native hook keys at registration time.
3. Matchers (e.g. Write|Edit on post-tool-use) stay a hook registration concern — optional future metadata.activation-matcher.
4. Does not replace Claude disable-model-invocation, Cursor alwaysApply, or "Internal skill:" description prefixes — those answer who may invoke, not which hook event.

Examples

Opt-in persona (description-triggered):

---
name: security-auditor
description: Use when the user asks for a security audit or reviewer stance.
metadata:
  persona: "true"
  activation: per-situation
---

Discipline injected at chat open:

---
name: commit-discipline
description: Internal skill for commit discipline hook injection.
metadata:
  activation: session-start
---

Non-goals (phase 1)

• Hook stdout contracts / payload schemas
• Requiring all hosts to implement every mapped event
• Promoting activation to a top-level required frontmatter field (defer until hosts converge)

Compatibility

• Omitted key → treat as per-situation
• Unknown metadata keys already ignored by spec-compliant clients
• No breaking change to required frontmatter (name, description)

Suggested spec text

activation (optional, string, under metadata): Normalized hook lifecycle event for this skill. Values are lowercase kebab-case names from the hook event registry (see mapping table). Default: per-situation when omitted — load via description without a hook. Does not replace hook matchers or invoker-control fields.

Suggested rollout

Phase 1: Document as recommended metadata convention (this RFC).

Phase 2: Hosts and tooling read metadata.activation and map to native hook config (e.g. cyber-skills hook register).

Reference implementation

• cyber-skills activation proposal draft
• Cursor third-party hooks mapping

Questions for maintainers

1. Metadata appendix vs companion doc — which fits the spec governance model?
2. Should the registry live in-spec or in a versioned companion artifact (like client integration guides)?
3. Overlap with #57: should advisory activation signals and hook lifecycle events be kept strictly separate namespaces?

[unional]

Canonical thread: consolidating this RFC into #57 (comment)

Revision: drop metadata.activation; use top-level activation.lifecycle (merged with @venikman signals / context / relevance model from #57).