Skill Runtime

Compilation pipeline, layered skill sources, and runtime registry for active skill execution.

Synopsis

Skills are discovered and executed through the MCP server:

find_skill("commit feature")
run_skill("task.git.commit_feature")

Compiler CLI:

python -m skill_runtime.compiler.cli build \
  --repo-root . --output-root src/skill_runtime/generated

Description

The skill runtime compiles Markdown-authored skills into Python modules, maintains a deterministic registry mapping canonical skill IDs to compiled classes, and supports layered skill scoping.

Compilation pipeline: Markdown source → parse (extract metadata, sections, steps) → intermediate representation → codegen (Python modules + registry).

Layered sources: skills are resolved from multiple layers with override semantics:

  1. Framework (skills/ in the Apogee repo)

  2. Organization (via APOGEE_ORG_SKILLS env var)

  3. Team (via APOGEE_TEAM_SKILLS env var)

  4. Repository (project-local skills)

  5. User (via APOGEE_USER_SKILLS env var)

Higher layers override lower layers by skill ID.

Layering example: suppose the framework ships a skill task.docs.create_rst that generates RST stubs with default templates. An organization layer provides its own task.docs.create_rst with company-specific templates and header conventions. At runtime, the org-layer version shadows the framework version — callers of run_skill("task.docs.create_rst") get the org-layer behavior without any change to invocation:

Layer 1 (framework):  skills/task/docs/create_rst.md       <- shadowed
Layer 2 (org):        $APOGEE_ORG_SKILLS/task/docs/create_rst.md  <- active

The same override applies at every layer boundary: a team skill shadows an org skill, a repo skill shadows a team skill, and so on.

Reference

Key modules

  • base.py — BaseSkill abstract class (root contract for all compiled skills)

  • registry.py — SkillRegistry class (runtime lookup by skill_id; loads from generated registry)

  • compiler/parser.py — parse_skill_source() parses Markdown into normalized IR

  • compiler/codegen.py — render_module(), render_registry() generate deterministic Python

  • compiler/builder.py — compile_skill_sources(), build_compiled_skills(), check_compiled_skills()

  • compiler/cli.py — CLI with build and check subcommands

CLI flags

Flag

Description

--repo-root

Repository root

--output-root

Output directory for generated modules

--source

Skill source directory (repeatable)

--all-framework

Include all framework skills

--effective-layers

Show resolved layer stack

Examples

# Build compiled skills
python -m skill_runtime.compiler.cli build --repo-root .

# Check compiled skills are fresh
python -m skill_runtime.compiler.cli check --repo-root .

What running a skill looks like

When you call run_skill("task.git.commit_feature"), the MCP server returns a prepared prompt — a structured contract that your AI assistant follows. The prompt contains:

  • Inputs — templated variables (${project_root}, ${feature_slug}) resolved from project state

  • Hard rules — constraints the agent must not violate

  • Ordered steps — numbered phases with specific outputs

  • Required output — what the agent must return when done

The skill does not run code directly. It prepares the instruction; your AI assistant executes it. Example flow for commit_feature:

  1. Agent examines the diff and detects single- or multi-feature scope

  2. Agent proposes commit groupings with conventional messages

  3. Agent runs the test suite after each code-touching commit

  4. Agent returns per-commit summaries and a final recap

Skills are Markdown files compiled into Python modules. Each skill declares a mode (read_only, writes_code, writes_tests, writes_docs, writes_config) that tells the host what kind of changes to expect.

Key Skill Collections

The framework ships 102 skills across 13 workflow suites, 13 task domains, and 6 repo-init skills. See skills/CATALOG.md for the full inventory.

Multi-step workflow suites (ordered, multi-phase):

  • feature_implementation — single-feature lifecycle: design, plan scaffolding, readiness gate

  • multi_feature_design — batch feature design: specs, adversarial review, implementation order, test definitions

  • bug_investigation — structured triage, CPG root-cause analysis, fix design, implementation, validation

  • code_porting — language-to-language porting with parity tracking and test verification (13 steps)

  • large_systems_change — 7-phase workflow for changes to massive codebases (kernel, Kubernetes, LLVM)

  • docs-create — greenfield doc generation (plan, author, Sphinx setup)

  • docs-restructure — restructure existing RST/man docs

  • doc_remediation — fix underperforming docs: baseline, positioning, narratives, examples

  • test_harness_authoring — build a test engine from scratch

  • test_harness_porting — port existing tests to data-driven TOML/YAML definitions

  • cpg_analysis — multi-tool CPG orchestration: impact review, security audit, similarity search

Single-shot task skills:

  • audit — codebase health, adoption metrics, duplication detection, dead code

  • testing — bootstrap unit tests, increase coverage, add integration and OS-contract tests

  • docs — audit docs vs code, generate codebase descriptions, check links and examples

  • cpg — impact check, blast radius, taint audit, bug triage

  • git — adaptive commits with test running, release tagging with changelog

  • design — conversational rubber-duck design exploration

  • review — format and post review comments

  • personas — 10 role-based lenses (engineer, architect, code-review, prodsec, legal, docs-writer, etc.)

  • build — Makefile-to-justfile conversion

  • release — version bumping across pyproject.toml, Cargo.toml, conf.py

Setting up team skill layers

To standardize workflows across a team, create an org or team skill layer and point developers at it via environment variables.

Step 1 — Create the layer directory

Mirror the framework skills/ structure. Only include skills you want to override or add — everything else inherits from the framework:

my-team-skills/
├── tasks/
│   └── docs/
│       └── create_rst.md      # team-specific RST templates
└── workflows/
    └── feature_implementation/
        └── 01_plan_scaffolding.md  # team plan conventions

Step 2 — Set the environment variable

Add to your team’s shell profile or CI config:

# Organization-wide (broadest)
export APOGEE_ORG_SKILLS=/path/to/org-skills

# Team-specific (narrows org)
export APOGEE_TEAM_SKILLS=/path/to/my-team-skills

# Per-developer (narrowest)
export APOGEE_USER_SKILLS=/path/to/user-skills

Step 3 — Recompile with layers

python -m skill_runtime.compiler.cli build \
  --effective-layers --emit-registry

The compiler merges all layers. Narrower layers shadow broader ones by skill ID — a team skill with the same relative path as a framework skill replaces it completely.

Immutable gate protection: if a broader layer marks a skill’s gate as immutable: true, narrower layers cannot shadow that skill. This prevents teams from bypassing org-level governance policies.

Distributing to developers: check the team skill directory into a shared repo. Developers clone it and set the env var. The MCP server picks up the compiled registry on startup — each skill carries a source_layer field so hosts can show which layer it came from.

Note

This page is also available as a man page: man apogee-skill-runtime

See Also