# RFC-0002: Gateway Protocol
> **Version:** 0.2.1 | **Status:** normative | **Phase:** test
---
## 1. Summary
### [RFC-0002:C-OVERVIEW] Overview (Informative) <a id="rfc-0002c-overview"></a>
The gateway is how agents access skill content on-demand. Rather than loading entire skills into context, agents use gateway commands to retrieve specific sections as needed.
Gateway commands operate on the **source** directory, not the compiled stub. This ensures agents always see current content without requiring a rebuild.
Every gateway access is logged per [RFC-0007:C-LOGGING](../rfc/RFC-0007.md#rfc-0007c-logging), enabling skill authors to understand which content agents actually use.
**Gateway commands:**
- `outline` — List all sections in a skill
- `show` — Retrieve section content
- `open` — Retrieve file content
- `sources` — List source files (tree-style)
See [RFC-0007:C-COMMANDS](../rfc/RFC-0007.md#rfc-0007c-commands) for the complete command registry with parameters and interface availability.
*Since: v0.1.0*
---
## 2. Specification
### [RFC-0002:C-OUTLINE] Outline Command (Normative) <a id="rfc-0002c-outline"></a>
**Syntax:** `skc outline <skill> [--level <n>]`
The outline command MUST scan all `.md` files in the skill's source directory and extract headings.
**Options:**
| `--level <n>` | Maximum heading level to include (1-6, default: unlimited) |
When `--level` is provided, the command MUST only output headings with level ≤ n. For example, `--level 2` shows only `#` and `##` headings.
**Output format:**
The command MUST output a structured list of headings with:
- Heading level (1-6)
- Heading text
- File path (relative to skill root)
**Ordering:**
Headings MUST be listed in file order, with files sorted lexicographically by relative path (bytewise ASCII order). No special-case ordering is permitted.
**Example output:**
```
SKILL.md
# Skill Name
## Getting Started
## API Reference
### Authentication
### Endpoints
references/advanced.md
# Advanced Topics
## Performance
```
With `--level 2`:
```
SKILL.md
# Skill Name
## Getting Started
## API Reference
references/advanced.md
# Advanced Topics
## Performance
```
*Since: v0.1.0*
### [RFC-0002:C-SHOW] Show Command (Normative) <a id="rfc-0002c-show"></a>
**Syntax:** `skc show <skill> --section "<heading>" [--file <path>] [--max-lines <n>]`
The show command MUST locate the specified heading and return its content.
**Options:**
| `--file <path>` | Limit search to specific file |
| `--max-lines <n>` | Maximum lines to return (default: unlimited) |
When `--max-lines` is provided, the command MUST truncate output to the first n lines. If content is truncated, the command MUST append a line:
`... (N more lines)`
**Index-based lookup:**
The command MUST use the pre-built headings index from [RFC-0004:C-INDEX](../rfc/RFC-0004.md#rfc-0004c-index) instead of parsing files at runtime. If the index is missing or stale, the command MUST exit with error E002 per [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes).
**Query normalization:**
Before matching, the query MUST be normalized:
1. Trim leading/trailing whitespace
2. If the query contains ` — ` (em-dash with spaces), extract only the part before it
This allows queries copied from compiled stubs (which may include descriptions) to work correctly.
**Heading matching:**
- Matching MUST be case-insensitive
- If `--file` is provided, search only that file; otherwise search all indexed headings
**Content extraction:**
The command MUST read content from the source file using the `start_line` and `end_line` from the index. Lines are 1-based.
**Multiple matches:**
If multiple headings match, the command MUST return the first match and write a warning to stderr in the form:
`warning: multiple matches for "<heading>"; showing first`
The command MUST exit with status 0 in this case.
**No match with suggestions:**
If no heading matches, the command MUST:
1. Search for similar headings (case-insensitive prefix match or substring match)
2. If suggestions found, include them in the error message:
```bash
error[E020]: section not found: '<query>'
Did you mean one of these?
- <suggestion1> (<file1>)
- <suggestion2> (<file2>)
```
3. Limit suggestions to 5 entries
4. Exit with non-zero status
*Updated in v0.2.0: Added index-based lookup, query normalization (em-dash stripping), and suggestions on no match.*
*Since: v0.1.0*
### [RFC-0002:C-OPEN] Open Command (Normative) <a id="rfc-0002c-open"></a>
**Syntax:** `skc open <skill> <path> [--max-lines <n>]`
The open command MUST return the contents of the specified file.
**Options:**
| `--max-lines <n>` | Maximum lines to return (default: unlimited) |
When `--max-lines` is provided, the command MUST truncate output to the first n lines. If content is truncated, the command MUST append a line:
`... (N more lines)`
**Path validation:**
- The path MUST be relative to the skill source root
- The path MUST NOT contain `..` sequences that escape the skill root
- The path MUST refer to a file (not a directory)
**Content:**
The command MUST return the file contents as-is without transformation (except for `--max-lines` truncation).
**File type:**
The `open` command is NOT restricted to `.md` files. It can retrieve any file within the skill source directory. This enables retrieval of search results from non-`.md` files (e.g., `.txt`).
**Path safety:**
The command MUST reject any path that would resolve outside the skill source directory after canonicalization. See [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes) for error E012.
**No match:**
If the file does not exist, the command MUST exit with error E021 per [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes).
*Since: v0.1.0*
### [RFC-0002:C-ERRORS] Error Handling (Normative) <a id="rfc-0002c-errors"></a>
All gateway command 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. Gateway commands use:
| Skill resolution failed | E001 or E010 |
| Path escapes skill root | E012 |
| Section not found | E020 |
| File not found | E021 |
| Directory not found | E022 |
| 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.
- **E012**: `skc open` path or `skc sources --dir` path would escape the skill root after canonicalization
- **E020**: `skc show --section` finds no matching heading
- **E021**: `skc open` target file does not exist
- **E022**: `skc sources --dir` target directory does not exist
- **E100**: Unknown flag, missing required value, or other CLI parsing failure
*Since: v0.1.0*
### [RFC-0002:C-SOURCES] Sources Command (Normative) <a id="rfc-0002c-sources"></a>
**Syntax:** `skc sources <skill> [options]`
The sources command MUST list all files in the skill's source directory in a tree-style format.
**Options:**
| `--depth <n>` | Maximum tree depth to display (default: unlimited) |
| `--dir <path>` | Scope listing to a subdirectory |
| `--limit <n>` | Maximum entries to display (default: 100) |
| `--pattern <glob>` | Filter files by glob pattern (e.g., `*.md`) |
| `--format <fmt>` | Output format: `text` (default) or `json` |
**Output format:**
The command MUST output a tree-style directory listing:
- Files are listed with their relative paths
- Directories that are not expanded MUST show a file count suffix: `dirname/ (N files)`
- When `--limit` is exceeded, output MUST end with a truncation indicator: `... (N more)`
**Ordering:**
Entries MUST be sorted lexicographically by relative path (bytewise ASCII order), with directories listed before files at each level.
**Example output:**
```
$ skc sources cuda --depth 2
cuda/
├── SKILL.md
├── references/
│ ├── compilation.md
│ ├── cuda-driver-docs/ (156 files)
│ ├── cuda-runtime-docs/ (89 files)
│ ├── debugging-tools.md
│ └── ... (8 more)
```
**Scoped listing:**
When `--dir` is provided, the command MUST:
- Validate that the path exists within the skill root
- Display the subtree rooted at that directory
- Apply `--depth` relative to the specified directory
**Path safety:**
The command MUST reject any `--dir` path that would resolve outside the skill source directory after canonicalization. See [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes) for error E012.
*Since: v0.1.0*
---
## Changelog
### v0.2.1 (2026-01-31)
Add missing --format support for `skc sources`
### v0.2.0 (2026-01-31)
C-SHOW updated with em-dash stripping and suggestions
### v0.1.0 (2026-01-30)
Initial release