# RFC-0001: Skill Compilation
> **Version:** 0.2.1 | **Status:** normative | **Phase:** test
---
## 1. Summary
### [RFC-0001:C-OVERVIEW] Overview (Informative) <a id="rfc-0001c-overview"></a>
Skill compilation transforms a skill source directory into a runtime-ready artifact.
The compiler reads an [Agent Skills](https://agentskills.io/) 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) <a id="rfc-0001c-input"></a>
The compiler MUST accept any directory that is a valid Agent Skill per [RFC-0000:C-COMPAT-FORMAT](../rfc/RFC-0000.md#rfc-0000c-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) <a id="rfc-0001c-output"></a>
The compiler MUST produce the following outputs in the runtime directory:
1. `SKILL.md` — the compiled stub (see [RFC-0001:C-STUB](../rfc/RFC-0001.md#rfc-0001c-stub))
2. `.skillc/manifest.json` — build metadata (see [RFC-0001:C-MANIFEST](../rfc/RFC-0001.md#rfc-0001c-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) <a id="rfc-0001c-stub"></a>
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](../rfc/RFC-0001.md#rfc-0001c-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) <a id="rfc-0001c-manifest"></a>
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) <a id="rfc-0001c-errors"></a>
All compilation errors MUST exit with status 1 and print an error message to stderr.
**Error codes:**
See [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes) for canonical error messages. This RFC uses:
| Skill resolution failed | E001 or E010 |
| Missing frontmatter field | E011 |
| Path escapes skill root | E012 |
| Invalid CLI option | E100 |
**Usage:**
- **E001/E010**: Skill resolution failed per [RFC-0007:C-RESOLUTION](../rfc/RFC-0007.md#rfc-0007c-resolution). See [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-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) <a id="rfc-0001c-sections"></a>
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:
```yaml
---
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) <a id="rfc-0001c-constraints"></a>
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) <a id="rfc-0001c-deployment"></a>
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
| Flag | Default | Effect |
|------|---------|--------|
| `--global` | false | Force SSOT to `~/.skillc/runtime/` regardless of source |
| `--target <agents>` | claude | Which agent directories to deploy to (comma-separated) |
| `--copy` | false | Force copy instead of symlink/junction |
| `--force` | false | Overwrite 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