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-0002: Gateway Protocol

Version: 0.2.1 | Status: normative | Phase: test

1. Summary

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

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, 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 for the complete command registry with parameters and interface availability.

Since: v0.1.0

2. Specification

[RFC-0002:C-OUTLINE] Outline Command (Normative)

Syntax: skc outline <skill> [--level <n>]

The outline command MUST scan all .md files in the skill’s source directory and extract headings.

Options:

OptionDescription
--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)

Syntax: skc show <skill> --section "<heading>" [--file <path>] [--max-lines <n>]

The show command MUST locate the specified heading and return its content.

Options:

OptionDescription
--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 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.

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: 
    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)

Syntax: skc open <skill> <path> [--max-lines <n>]

The open command MUST return the contents of the specified file.

Options:

OptionDescription
--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 for error E012.

No match: If the file does not exist, the command MUST exit with error E021 per RFC-0005:C-CODES.

Since: v0.1.0

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

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

Error codes: See RFC-0005:C-CODES for canonical error messages. Gateway commands use:

ConditionError Code
Skill resolution failedE001 or E010
Path escapes skill rootE012
Section not foundE020
File not foundE021
Directory not foundE022
Invalid CLI optionE100

Usage:

  • E001/E010: Skill resolution failed per RFC-0007:C-RESOLUTION. See RFC-0005:C-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)

Syntax: skc sources <skill> [options]

The sources command MUST list all files in the skill’s source directory in a tree-style format.

Options:

OptionDescription
--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 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