Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFC-0001: Skill Compilation

Version: 0.2.1 | Status: normative | Phase: test

1. Summary

[RFC-0001:C-OVERVIEW] Overview (Informative)

Skill compilation transforms a skill source directory into a runtime-ready artifact.

The compiler reads an Agent Skills directory, extracts metadata and structure, and produces:

  1. A stub — a compact SKILL.md that instructs agents to use gateway commands
  2. A manifest — metadata for build tracking and change detection

Compilation enforces progressive disclosure: the stub exposes structure without content, directing agents to retrieve sections on-demand through skillc.

Since: v0.1.0

2. Specification

[RFC-0001:C-INPUT] Compilation Input (Normative)

The compiler MUST accept any directory that is a valid Agent Skill per RFC-0000:C-COMPAT-FORMAT.

The compiler MUST read the following from the source directory:

  • SKILL.md — extract name and description from YAML frontmatter
  • All .md files — extract heading structure for outline generation
  • Directory structure — enumerate files for source listing

The compiler MUST fail with a clear error if:

  • SKILL.md is missing
  • SKILL.md lacks required name or description frontmatter fields

Since: v0.1.0

[RFC-0001:C-OUTPUT] Compilation Output (Normative)

The compiler MUST produce the following outputs in the runtime directory:

  1. SKILL.md — the compiled stub (see RFC-0001:C-STUB)
  2. .skillc/manifest.json — build metadata (see RFC-0001:C-MANIFEST)

The compiler MUST create the runtime directory if it does not exist.

The compiler MUST NOT copy source content to the runtime directory. Only the stub, manifest, and log directories are permitted.

Since: v0.1.0

[RFC-0001:C-STUB] Stub Format (Normative)

The compiled stub MUST be a valid Agent Skills SKILL.md file.

The stub MUST include:

  • YAML frontmatter with name and description (preserved from source)
  • A notice that agents should use gateway commands, not read sources directly
  • A statement that agents SHOULD prefer MCP tools (skc_outline, skc_show, skc_search, etc.) if the skillc MCP server is available, for better performance and structured output
  • Gateway command examples as CLI fallback: skc outline, skc show --section, skc open, skc sources
  • A section listing per RFC-0001:C-SECTIONS

The stub MUST NOT include:

  • Source content beyond headings
  • Source file listings (use skc sources instead)
  • Implementation details or internal paths
  • References to absolute filesystem paths

The stub format is designed to fit within agent context limits while providing enough structure for agents to navigate the skill.*

Since: v0.1.0

[RFC-0001:C-MANIFEST] Manifest Format (Normative)

The manifest MUST be a JSON file located at .skillc/manifest.json in the runtime directory.

The manifest MUST include:

  • skill — the skill name
  • version — manifest schema version (integer)
  • built_at — ISO 8601 timestamp of compilation
  • source_hash — content hash for change detection

The source hash MUST be computed as SHA-256 over the sorted list of (relative_path, file_hash) pairs from the source directory. This enables the compiler to detect when sources have changed since the last build.

The manifest MAY include additional fields for future extensibility.

Since: v0.1.0

[RFC-0001:C-ERRORS] Error Handling (Normative)

All compilation errors MUST exit with status 1 and print an error message to stderr.

Error codes: See RFC-0005:C-CODES for canonical error messages. This RFC uses:

ConditionError Code
Skill resolution failedE001 or E010
Missing frontmatter fieldE011
Path escapes skill rootE012
Invalid CLI optionE100

Usage:

  • E001/E010: Skill resolution failed per RFC-0007:C-RESOLUTION. See RFC-0005:C-CODES for when to use each.
  • E011: SKILL.md exists but lacks required name or description frontmatter
  • E012: Symlink or path would escape the skill root directory
  • E100: Unknown flag, missing required value, or other CLI parsing failure

Since: v0.1.0

[RFC-0001:C-SECTIONS] Section Listing Rules (Normative)

The stub section listing (“Top Sections”) MUST be generated according to these rules:

SKILL.md Sections

For the main SKILL.md file, the compiler MUST:

  • Include all H1 headings at indent level 0
  • Include H2 headings at indent level 1 (as children of the preceding H1)
  • Exclude H3 and deeper headings (too detailed for stub)
  • Limit to 15 entries; if more exist, append “… (N more)” indicator

The first H1 is NOT treated specially — it is included like any other H1.

Other Markdown Files

For all other .md files in the skill directory:

  • Group all entries under a “References (query by title only)” label at indent level 0
  • The hint “(query by title only)” clarifies that descriptions are for context only
  • Use the first H1 heading from each file at indent level 1
  • If a file has no H1 heading, use the relative file path as the label
  • If the file has frontmatter with a description field, append it inline after an em-dash: - Title — description
  • Description MUST be truncated to 120 characters with … if longer
  • Limit to 15 entries; if more exist, append “… (N more)” indicator
  • Files are listed in alphabetical order by path

The “References” section is only included if there are other .md files.

Reference File Frontmatter

Reference files MAY contain optional YAML frontmatter:

---
description: "Brief description of this reference document"
---

The description field:

  • Is optional (no warning if absent)
  • Should be concise (≤120 characters recommended)
  • Is displayed inline in the stub after the title
  • Is NOT part of the queryable section name

File Ordering

Files MUST be processed in this order:

  1. SKILL.md first (main document)
  2. Other .md files in alphabetical order by path

Example Output

## Top Sections

- Rust CLI
  - Default Flow
  - Decision Tree
- Advanced Topics
  - Performance
- References (query by title only)
  - Clap Patterns — Advanced argument parsing examples
  - Error Handling — anyhow vs thiserror patterns
  - TUI Guide

In this example:

  • “Rust CLI” and “Advanced Topics” are H1s from SKILL.md
  • “Default Flow”, “Decision Tree”, “Performance” are H2s from SKILL.md
  • “References (query by title only)” is the fixed grouping label with hint
  • “Clap Patterns” and “Error Handling” have descriptions from their frontmatter
  • “TUI Guide” has no description (frontmatter absent or no description field)
  • When querying, use skc show --section "Clap Patterns" (not the full line with description)

Since: v0.2.0

Since: v0.2.0

3. Constraints

[RFC-0001:C-CONSTRAINTS] Compilation Constraints (Normative)

The compiler MUST enforce the following constraints:

Stub size: The compiled stub MUST NOT exceed 100 lines. If the source skill is too large to summarize within this limit, the compiler MUST truncate sections and indicate truncation.

Section limit: The stub section listing MUST include at most 12 top-level headings. Additional headings MUST be omitted with an indication that more exist.

Command restrictions:

  • skc outline — Lists structure from .md files only
  • skc show — Retrieves sections from .md files only
  • skc open — Retrieves any file within the skill root (not restricted to .md)
  • skc sources — Lists all files within the skill root

Path safety: The compiler MUST reject source directories containing symlinks that escape the skill root.

Since: v0.1.0

4. Compilation Output

[RFC-0001:C-DEPLOYMENT] Deployment Strategy (Normative)

The compiler MUST compile to a Single Source of Truth (SSOT) location and deploy to agent directories.

SSOT Locations

Compiled skills MUST be stored in one of these SSOT locations:

  • Project-local SSOT: .skillc/runtime/<skill-name>/
  • Global SSOT: ~/.skillc/runtime/<skill-name>/

Agent Directories

Agent directories are where AI agents discover skills:

  • ~/.claude/skills/<skill-name>/
  • ~/.cursor/skills/<skill-name>/

Agent directories contain links (or copies) pointing to the SSOT location.

Default Behavior (Local-First)

When compiling a project-local source (.skillc/skills/), the compiler MUST:

  1. Output to project-local SSOT (.skillc/runtime/<skill-name>/)
  2. Deploy to agent directory (~/.claude/skills/<skill-name>/ by default)

When compiling a global source (~/.skillc/skills/), the compiler MUST:

  1. Output to global SSOT (~/.skillc/runtime/<skill-name>/)
  2. Deploy to agent directory (~/.claude/skills/<skill-name>/ by default)

CLI Flags

FlagDefaultEffect
--globalfalseForce SSOT to ~/.skillc/runtime/ regardless of source
--target <agents>claudeWhich agent directories to deploy to (comma-separated)
--copyfalseForce copy instead of symlink/junction
--forcefalseOverwrite existing skill during import

Deployment Methods

The compiler MUST deploy from SSOT to agent directories using these methods:

  1. Unix: Create symlink (default)
  2. Windows: Create directory junction (no admin required)
  3. Fallback: Copy directory contents with warning

The --copy flag forces copy mode on all platforms.

Deployment Behavior

When deploying, the compiler MUST:

  1. Ensure the parent directory exists
  2. Remove any existing symlink/junction at the target path
  3. Create a symlink/junction pointing to the SSOT directory (or copy if --copy)
  4. Report each deployment with method used

The compiler MUST NOT overwrite an existing directory (non-symlink) without --force.

Since: v0.1.0

Changelog

v0.2.1 (2026-01-31)

Add reference file description support

v0.2.0 (2026-01-31)

Add C-SECTIONS

v0.1.0 (2026-01-30)

Initial release