feat(activation): add provider-agnostic Chalk activation contract

Add the activation contract specification for provider-agnostic skill discovery. Introduces metadata-version 2 with activation-intents, activation-events, activation-artifacts, capabilities, and risk-level fields across 13 core skills. Includes updated validation scripts, contributing guide, changelog, and activation documentation.

Author: breadoncee

CHANGELOG.md

@@ -9,14 +9,18 @@ The format is inspired by Keep a Changelog and uses SemVer semantics for skill v
 ### Added
 
 - Metadata contract docs: `docs/open-source-scope.md`, `docs/skill-contract.md`
+- Activation model spec: `docs/activation-model.md`
+- Example project activation manifest: `docs/examples/activation-skills.yaml`
 - Provider-agnostic validation script: `scripts/validate-skills.sh`
 - Skill index manifest: `skills/skills-index.yaml`
 - New skill: `skills/project-skill-creator/SKILL.md`
 
 ### Changed
 
 - Standardized frontmatter across all shipped skills (`owner`, `version`, `metadata-version`)
+- Extended the frontmatter contract with provider-agnostic activation metadata (`metadata-version: "2"`)
 - Updated `README.md` for unified `.chalk/skills` architecture and ownership/version policy
+- Updated scaffolding and validation tooling for activation metadata
 
 ### Removed
 

CONTRIBUTING.md

@@ -36,6 +36,7 @@ scripts/init-skill.sh <skill-name> --description "..." --owner project --path .c
 
 - Keep `name`, folder name, and index entry aligned.
 - Include required frontmatter keys.
+- Use activation metadata only when it is provider-agnostic and reusable across projects.
 - Use `owner: chalk` for core repo skills.
 - Do not add provider-specific metadata files.
 - Keep `SKILL.md` concise and practical.
@@ -47,6 +48,7 @@ scripts/init-skill.sh <skill-name> --description "..." --owner project --path .c
 - Call out any compatibility impact.
 - Update `skills/skills-index.yaml` when adding or renaming skills.
 - Update `CHANGELOG.md` for notable user-facing behavior or contract changes.
+- Update `docs/activation-model.md` or the example manifest when changing activation semantics.
 
 ## Review Criteria
 

README.md

@@ -82,9 +82,14 @@ name: skill-name
 description: What this skill does and when to use it
 owner: chalk
 version: "1.0.0"
-metadata-version: "1"
+metadata-version: "2"
 allowed-tools: Read, Write, Glob, Grep
 argument-hint: "[what the user passes]"
+capabilities: docs.create, docs.update
+activation-intents: create doc, update doc
+activation-events: user-prompt
+activation-artifacts: .chalk/docs/**
+risk-level: low
 ---
 
 # Skill Title
@@ -98,9 +103,14 @@ argument-hint: "[what the user passes]"
 - `description` -- Drives auto-discovery; must include **what** and **when**
 - `owner` -- `chalk` for Chalk-managed skills, `project` for project-managed skills
 - `version` -- SemVer (`major.minor.patch`) for skill behavior
-- `metadata-version` -- Skill frontmatter schema version (currently `"1"`)
+- `metadata-version` -- Skill frontmatter schema version (currently `"2"`)
 - `allowed-tools` -- Restricts the agent to only the tools it needs
 - `argument-hint` -- Shows the user what to pass after the slash command
+- `capabilities` -- Optional comma-separated capability tags for routing and indexing
+- `activation-intents` -- Optional comma-separated trigger phrases
+- `activation-events` -- Optional comma-separated neutral event names
+- `activation-artifacts` -- Optional comma-separated repo paths or globs
+- `risk-level` -- Optional side-effect hint (`low`, `medium`, `high`)
 
 ## Where Skills Live
 
@@ -112,6 +122,8 @@ Canonical runtime location:
 
 No provider-specific metadata files are stored in this repository. `.chalk/skills/` remains the source of truth.
 
+Project activation rules live outside individual skills. Chalk reserves `.chalk/activation/skills.yaml` as the neutral project manifest location; see `docs/activation-model.md` and `docs/examples/activation-skills.yaml`.
+
 ## The `.chalk/` Folder
 
 Skills produce and maintain the `.chalk/` documentation structure:
@@ -157,6 +169,7 @@ Skills produce and maintain the `.chalk/` documentation structure:
 ## Open Source Contract
 
 - Scope and boundaries: `docs/open-source-scope.md`
+- Activation model: `docs/activation-model.md`
 - Skill metadata/compatibility contract: `docs/skill-contract.md`
 - Versioning policy: `docs/versioning.md`
 - Review checklist: `docs/review-checklist.md`
@@ -173,7 +186,7 @@ make init-skill NAME=my-skill DESC="what it does and when to use it" OWNER=proje
 ## Adding a New Skill
 
 1. Create a folder: `skills/<skill-name>/`
-2. Add a `SKILL.md` with frontmatter (`name`, `description`, `owner`, `version`, `metadata-version`; plus optional `allowed-tools`, `argument-hint`)
+2. Add a `SKILL.md` with frontmatter (`name`, `description`, `owner`, `version`, `metadata-version`; plus optional `allowed-tools`, `argument-hint`, and activation metadata)
 3. Write the workflow as numbered steps
 4. Add templates or scripts in `assets/` if needed
 5. Keep `SKILL.md` under 500 lines; use progressive disclosure for detail

docs/activation-model.md

@@ -0,0 +1,93 @@
+# Activation Model
+
+## Purpose
+
+Chalk activation keeps skills provider-agnostic while giving runtimes enough structure to decide when to load them. The activation model lives at the project level, not inside a provider adapter.
+
+- Skills declare reusable activation hints in `SKILL.md`
+- Projects declare local routing rules in `.chalk/activation/skills.yaml`
+- Runtimes such as Chalk Browser can compile or interpret those rules for a specific agent
+
+This repository defines the contract only. It does not ship a live router or provider-specific hooks.
+
+## Design Rules
+
+- Keep rules deterministic before semantic.
+- Keep project-specific routing in the project manifest, not in shared skills.
+- Keep action names neutral so they can map to Claude hooks, RuleZ, or another adapter later.
+- Default to audit-first rollout for new rule sets.
+
+## Project Manifest Location
+
+Real projects should store the manifest at:
+
+```text
+.chalk/activation/skills.yaml
+```
+
+An example file for contributors lives at `docs/examples/activation-skills.yaml`.
+
+## Manifest Shape
+
+```yaml
+version: "1"
+default-mode: audit
+rules:
+  - id: create-plan-from-user-request
+    description: Activate planning when the user explicitly asks for a plan.
+    priority: 100
+    when:
+      events: [user-prompt]
+      prompt-contains: [plan, roadmap, approach]
+    activate:
+      skills: [create-plan]
+```
+
+## Supported Matchers
+
+- `events`
+  - Neutral runtime events such as `user-prompt`, `session-start`, `pre-tool-use`, `post-tool-use`, `pre-compact`, `session-end`
+- `prompt-contains`
+  - Plain-language trigger phrases
+- `paths-any`
+  - Repo paths or globs related to the request or changed files
+- `capabilities-any`
+  - Capability tags exported by the referenced skills
+- `risk-max`
+  - Maximum allowed `risk-level` for auto-activation in the rule
+
+Projects may add more matchers later, but they should stay declarative and portable.
+
+## Supported Actions
+
+- `activate.skills`
+  - Inject or prioritize one or more named Chalk skills
+- `annotate`
+  - Add a deterministic note explaining what matched
+- `block`
+  - Prevent an unsafe automatic activation and require user confirmation
+
+The runtime decides how these actions map to a specific agent. This repository only defines the neutral intent.
+
+## Conflict Resolution
+
+1. Highest `priority` wins.
+2. If priorities tie, the rule with the narrower path scope wins. A rule with no `paths-any` matcher is considered the widest possible scope (matches all paths).
+3. If rules still tie, prefer the lower `risk-level`.
+4. If there is still a tie, activate no new skill and surface an audit note.
+
+## Relationship To Skill Metadata
+
+Skill metadata should stay broad and reusable:
+
+- Good: `capabilities: docs.create, docs.update`
+- Good: `activation-artifacts: .chalk/docs/**`
+- Avoid: customer names, private repo paths, vendor-only event names
+
+Project manifests are where repo-specific context belongs.
+
+## Rollout Guidance
+
+- Start with `default-mode: audit`
+- Review false positives and false negatives before enabling stronger automation
+- Keep a fallback `AGENTS.md` path even when activation rules exist

docs/examples/activation-skills.yaml

@@ -0,0 +1,42 @@
+version: "1"
+default-mode: audit
+rules:
+  - id: setup-chalk-from-user-prompt
+    description: Activate Chalk setup when the user asks to initialize Chalk in a repo.
+    priority: 100
+    when:
+      events: [user-prompt]
+      prompt-contains: [set up chalk, initialize chalk, bootstrap chalk]
+    activate:
+      skills: [setup-chalk]
+
+  - id: populate-chalk-docs
+    description: Activate doc population after setup or when the user asks to fill the profile docs.
+    priority: 90
+    when:
+      events: [user-prompt]
+      prompt-contains: [populate chalk docs, fill chalk docs, bootstrap profile docs]
+      paths-any: [.chalk/docs/**]
+    activate:
+      skills: [setup-docs]
+
+  - id: create-plan-from-intent
+    description: Route planning requests to the planning skill.
+    priority: 80
+    when:
+      events: [user-prompt]
+      prompt-contains: [create plan, make a plan, roadmap, approach]
+      capabilities-any: [planning.create]
+      risk-max: low
+    activate:
+      skills: [create-plan]
+
+  - id: review-pipeline-from-intent
+    description: Route explicit review requests to the review pipeline.
+    priority: 80
+    when:
+      events: [user-prompt]
+      prompt-contains: [review my changes, run review, self review]
+      paths-any: [.chalk/reviews/**]
+    activate:
+      skills: [review-changes]

docs/open-source-scope.md

@@ -8,13 +8,15 @@
 
 - Skill definitions under `skills/<skill-name>/SKILL.md`
 - Shared skill metadata/index (`skills/skills-index.yaml`)
+- Provider-agnostic activation metadata and project manifest docs
 - Skill validation and quality tooling (`scripts/validate-skills.sh`)
 - Documentation for skill authoring, ownership, and versioning
 - Contributor-facing templates and governance docs
 
 ## Out of Scope
 
 - Chalk Browser app source code and internal orchestration internals
+- Runtime routing engines, policy daemons, and adapter execution logic
 - Closed-source runtime adapters and product-only integrations
 - Secrets, API keys, internal telemetry payloads, or private infra config
 - Vendor-specific skill metadata formats (provider-specific config files)
@@ -25,6 +27,7 @@ This repository must remain provider-agnostic:
 
 - Do not add provider-specific metadata files inside skill packages.
 - Keep skill contracts defined by `SKILL.md` frontmatter and markdown body.
+- Keep activation manifests declarative and adapter-neutral.
 - Keep tooling generic and portable across AI coding environments.
 
 ## Relationship to Chalk Browser

docs/review-checklist.md

@@ -5,6 +5,7 @@ Use this checklist for all `chalk-skills` pull requests.
 ## Contract Checks
 
 - [ ] Skill frontmatter includes required keys (`name`, `description`, `owner`, `version`, `metadata-version`)
+- [ ] Optional activation metadata is provider-agnostic and follows the documented schema
 - [ ] Skill name is kebab-case and matches folder name
 - [ ] Ownership rules are respected (`chalk-*` reserved for `owner: chalk`)
 - [ ] No provider-specific metadata files were added

docs/skill-contract.md

@@ -1,8 +1,9 @@
-# Skill Contract (v1)
+# Skill Contract (v2)
 
 ## Compatibility Contract
 
-- `metadata-version: "1"` defines the current frontmatter schema.
+- `metadata-version: "2"` defines the current frontmatter schema.
+- `metadata-version: "1"` remains valid for legacy skills that do not declare activation metadata.
 - All skills under `skills/` must satisfy this schema.
 - Breaking schema changes require a new metadata version.
 
@@ -16,7 +17,7 @@ name: <kebab-case>
 description: <what it does and when to use it>
 owner: <chalk|project>
 version: "<major.minor.patch>"
-metadata-version: "1"
+metadata-version: "2"
 ---
 ```
 
@@ -25,6 +26,11 @@ metadata-version: "1"
 ```yaml
 allowed-tools: Read, Glob, Write
 argument-hint: "[optional arguments]"
+capabilities: docs.create, docs.update
+activation-intents: create doc, update doc
+activation-events: user-prompt
+activation-artifacts: .chalk/docs/**
+risk-level: low
 ```
 
 ## Naming Rules
@@ -38,6 +44,32 @@ argument-hint: "[optional arguments]"
 - `owner: chalk`: Chalk-managed skill in this repository
 - `owner: project`: Project-managed skill in project-level stores
 
+## Activation Metadata
+
+`metadata-version: "2"` adds optional activation hints that stay provider-agnostic and can be consumed by Chalk Browser or another adapter later.
+
+- `capabilities`
+  - Comma-separated canonical capability tags
+  - Use lowercase dot namespaces such as `docs.create` or `review.orchestrate`
+- `activation-intents`
+  - Comma-separated user-facing trigger phrases
+  - Keep them broad and reusable; project-specific routing belongs in project manifests
+- `activation-events`
+  - Comma-separated event names from this set:
+    - `user-prompt`
+    - `session-start`
+    - `pre-tool-use`
+    - `post-tool-use`
+    - `pre-compact`
+    - `session-end`
+- `activation-artifacts`
+  - Comma-separated repo paths or globs touched by the skill, such as `.chalk/docs/**`
+- `risk-level`
+  - One of `low`, `medium`, `high`
+  - Signals the skill's side-effect profile, not a security guarantee
+
+These fields are hints only. Project-specific activation rules live outside the skill in the neutral project manifest documented in `docs/activation-model.md`.
+
 ## Versioning Rules
 
 `version` follows SemVer:
@@ -60,5 +92,6 @@ Current validator enforces:
 - Name format and folder-name match
 - SemVer format
 - Ownership rules
-- `metadata-version` value
+- `metadata-version` value (`1` or `2`)
+- `metadata-version: "2"` activation metadata format when present
 - Provider-agnostic policy (fails on provider-specific metadata files)

docs/versioning.md

@@ -17,7 +17,8 @@ Use semantic versioning for behavior:
 
 Use this only for frontmatter schema changes.
 
-- Current value: `"1"`
+- Current value: `"2"`
+- Legacy value `"1"` is still accepted for pre-activation skills during migration
 - Bump only when required fields or field semantics change
 - Schema migrations must include:
   - migration notes
@@ -38,3 +39,4 @@ For any PR changing skill behavior:
 - Clarify wording in `setup-docs` rules only: `1.2.3 -> 1.2.4`
 - Add a new optional output section in `create-doc`: `1.2.3 -> 1.3.0`
 - Change `create-plan` output naming contract: `1.2.3 -> 2.0.0`
+- Add activation metadata support to the frontmatter schema: `metadata-version "1" -> "2"`