Canopy Runtime

Canopy Runtime

The execution engine for canopy-flavored skills. Any skill whose SKILL.md declares a ## Tree section is canopy-flavored and relies on this spec.

Skills root resolution

<skills-root> is the directory containing this canopy-runtime/SKILL.md. Recognized roots, first match wins:

• .agents/skills/ — cross-agent install (gh skill install default on Copilot and other hosts since gh 2.91)
• .claude/skills/ — Claude Code
• .github/skills/ — GitHub Copilot

All path references in this spec (e.g. <skills-root>/canopy-runtime/references/...) resolve relative to the matched root. Skills installed at any of the three locations are equally valid; what matters is consistency within a single project.

Platform detection (runtime self-identification)

The active platform is not derived from the skills-root path. The agent self-identifies which host it is and applies the matching runtime spec:

• Claude Code → apply <skills-root>/canopy-runtime/references/runtime-claude.md
• GitHub Copilot → apply <skills-root>/canopy-runtime/references/runtime-copilot.md
• Other hosts → halt with error: "This skill requires canopy-runtime, which currently supports Claude Code and GitHub Copilot only."

Signals an agent may use to identify itself (any one is sufficient):

• Self-knowledge — the agent knows which product it is (Claude Code, Copilot, etc.).
• Tool surface — native subagent / Task-tool capability is present on Claude Code.
• Workspace markers — CLAUDE.md at project root with the canopy-runtime marker block indicates Claude Code is the host; .github/copilot-instructions.md with the marker block indicates Copilot.

Manifest-aware spec loading

When a canopy-flavored skill is invoked, load only the spec slices it actually needs.

Read the skill's frontmatter for metadata.canopy-features. The value is a list naming feature groups the skill uses:

Manifest absent (back-compat). When the skill has no metadata.canopy-features, fall back to loading every file under references/ops/ plus references/skill-resources.md. The skill is older than canopy v0.21.0 (or /canopy improve hasn't been run on it). Behavior is unchanged from pre-v0.21.0; the canopy authoring agent will propose adding the manifest.

Always load references/skill-resources.md (skill anatomy, op lookup, tree format, safety preamble, manifest spec).

The runtime never refuses to run a skill because of a missing or under-declared manifest — drift is reported by /canopy validate, not enforced by the runtime. Soft adoption.

Activation

Activation is agent-mediated, not install-tool-mediated. This section is a contract that an agent runs the first time it loads canopy-runtime/SKILL.md in a given workspace. Pure CLI install paths (gh skill install, install.sh/install.ps1, plugin marketplace) only place files on disk — they do not (and cannot) execute this section. The marker block lands in the workspace's instructions file the first time an agent loads this SKILL.md and runs the steps below.

On first load by an agent, ensure the canopy-runtime marker block is present in the active platform's instructions file. This makes future sessions auto-load the runtime without rerunning this step.

1. Identify the active platform per Platform detection above.
2. Resolve the marker destination:
   • Claude Code → CLAUDE.md at the project root
   • GitHub Copilot → .github/copilot-instructions.md
3. If the destination file does not contain <!-- canopy-runtime-begin -->, write the canonical marker block defined in assets/constants/marker-block.md (alongside this SKILL.md). Apply the idempotent-write contract: CREATE if absent, APPEND if no markers, REPLACE if exactly one marker pair exists, WARN if multiple, REFUSE if mismatched.
4. Idempotent — running on a fully activated project is a no-op.

This replaces explicit /canopy activate once an agent has loaded the runtime at least once. For plugin and gh skill install paths the install itself is just file placement; the marker block is written when the next agent invocation loads this SKILL.md and runs Activation. The install.sh / install.ps1 paths additionally write the marker block during install (since those scripts run in a shell context and have no agent), so for those paths the project is already fully activated when the install completes.

What the runtime defines

• Sections — ## Agent (optional, soft-compat for EXPLORE), ## Tree (sequential execution pipeline), ## Rules (skill-wide invariants), ## Response: (output format). See references/skill-resources.md.
• Notation — << input source/options, >> captured output/displayed fields, | separator. See references/skill-resources.md.
• Primitives — sliced by feature, indexed by references/ops.md. Always-loaded slice: ops/core.md. On-demand: ops/interaction.md, ops/control-flow.md, ops/parallel.md, ops/subagent.md, ops/explore.md, ops/verify.md.
• Op lookup chain — <skill>/references/ops.md (or <skill>/references/ops/<name>.md) → consumer-defined cross-skill ops → canopy-runtime's primitive slices. See references/skill-resources.md. Older skills with <skill>/ops.md at root remain supported.
• Category directories — scripts/, references/, assets/{templates,constants,schemas,checklists,policies,verify}/. Each has defined behavior. See references/skill-resources.md.
• Tree syntax — markdown-list and box-drawing. Both recognized. See references/skill-resources.md.
• Safety preamble — fail-fast guard for agents loading the skill body without canopy-runtime active. See references/skill-resources.md.
• Subagent contract — see references/ops/subagent.md.
• Manifest — per-skill metadata.canopy-features. See references/skill-resources.md and the Manifest-aware spec loading section above.
• Platform-specific execution — Claude uses native subagents; Copilot falls back to fleet / custom-agent / inline sequential. See references/runtime-claude.md and references/runtime-copilot.md.

Not a user-invocable skill

canopy-runtime is hidden from the / menu (metadata.user-invocable: "false"). It is loaded:

• Ambiently via the canopy-runtime marker block (written by the Activation section above on first run, or by install scripts).
• Explicitly by the canopy authoring agent and canopy-debug trace skill at the top of their trees.
• On-demand by Claude's skill-description discovery when a canopy-flavored skill is invoked.