# RFC-0007: CLI Reference
> **Version:** 0.1.0 | **Status:** normative | **Phase:** test
---
## 1. Summary
### [RFC-0007:C-OVERVIEW] Overview (Informative) <a id="rfc-0007c-overview"></a>
RFC-0007 is the single source of truth for skillc's command-line interface.
This RFC specifies:
1. **Command Registry** — All commands, their parameters, and interface availability (CLI vs MCP)
2. **Skill Resolution** — How skill names/paths are resolved to source directories
3. **Access Logging** — How command invocations are logged for analytics
4. **Sync Command** — How fallback logs are merged to primary locations
5. **MCP Interface** — The Model Context Protocol server for agent integration
**Relationship to other RFCs:**
- [RFC-0001](../rfc/RFC-0001.md) — Skill Compilation (`build` command behavioral spec)
- [RFC-0002](../rfc/RFC-0002.md) — Gateway Protocol (`outline`, `show`, `open`, `sources` behavioral specs)
- [RFC-0003](../rfc/RFC-0003.md) — Usage Analytics (`stats` command behavioral spec)
- [RFC-0004](../rfc/RFC-0004.md) — Search Protocol (`search` command behavioral spec)
- [RFC-0005](../rfc/RFC-0005.md) — Error Code Registry (canonical error codes)
- [RFC-0006](../rfc/RFC-0006.md) — Scaffolding (`init` command behavioral spec)
Each feature RFC owns the behavioral specification for its commands. RFC-0007 provides the cross-cutting infrastructure that all commands share.
*Since: v0.1.0*
---
## 2. Specification
### [RFC-0007:C-COMMANDS] Command Registry (Normative) <a id="rfc-0007c-commands"></a>
This clause defines all skillc commands, their parameters, and interface availability.
**Interface Legend:**
- **CLI**: Command-line interface (`skc <command>`)
- **MCP**: Model Context Protocol tool (`skc_<command>`)
## Command Registry
| `init` | ✓ | ✓ | Initialize project or create skill |
| `list` | ✓ | ✓ | List all skillc-managed skills |
| `build` | ✓ | ✓ | Compile skill to runtime format |
| `lint` | ✓ | ✓ | Validate skill authoring quality |
| `outline` | ✓ | ✓ | List all sections in a skill |
| `show` | ✓ | ✓ | Retrieve section content |
| `open` | ✓ | ✓ | Retrieve file content |
| `sources` | ✓ | ✓ | List source files (tree-style) |
| `search` | ✓ | ✓ | Search skill content |
| `stats` | ✓ | ✓ | Usage analytics |
| `sync` | ✓ | — | Merge fallback logs to primary (CLI-only) |
| `mcp` | ✓ | — | Start MCP server (CLI-only) |
## Parameter Definitions
### init
| `name` | string | no | — | Skill name to create |
| `--global` | boolean | no | false | Create in global source store |
### list
| `--scope` | string | no | all | Filter: `project`, `global`, or `all` |
| `--status` | string | no | all | Filter: `normal`, `not-built`, `obsolete`, or `all` |
| `--limit` | number | no | unlimited | Maximum skills to return |
| `--pattern` | string | no | — | Filter by skill name (glob pattern) |
| `--check-obsolete` | boolean | no | false | Enable obsolete runtime detection |
See [RFC-0007:C-LIST](../rfc/RFC-0007.md#rfc-0007c-list) for full specification.
### build
| `skill` | string | yes | — | Skill name or path |
| `--global` | boolean | no | false | Force SSOT to global (~/.skillc/runtime/) |
| `--target` | string[] | no | claude | Target agents to deploy to (comma-separated) |
| `--copy` | boolean | no | false | Force copy instead of symlink/junction |
| `--force` | boolean | no | false | Overwrite existing skill during import |
**Behavior:**
- **Skill name**: Looks up skill in project source store (`.skillc/skills/`) then global (`~/.skillc/skills/`)
- **Path**: Imports skill to source store first, then builds (requires `--force` to overwrite existing)
Compiles to SSOT location (`.skillc/runtime/` for local sources, `~/.skillc/runtime/` for global) and deploys to agent directories via symlink. See [RFC-0001:C-DEPLOYMENT](../rfc/RFC-0001.md#rfc-0001c-deployment).
### lint
| `skill` | string | yes | — | Skill name or path |
| `--force` | boolean | no | false | Lint even if skill is compiled |
### outline
| `skill` | string | yes | — | Skill name or path |
| `level` | number | no | unlimited | Maximum heading level (1-6) |
### show
| `skill` | string | yes | — | Skill name or path |
| `section` | string | yes | — | Section heading to retrieve |
| `file` | string | no | — | Limit search to specific file |
| `max_lines` | number | no | unlimited | Maximum lines to return |
### open
| `skill` | string | yes | — | Skill name or path |
| `path` | string | yes | — | Relative path within skill |
| `max_lines` | number | no | unlimited | Maximum lines to return |
### sources
| `skill` | string | yes | — | Skill name or path |
| `depth` | number | no | unlimited | Maximum tree depth |
| `dir` | string | no | — | Scope to subdirectory |
| `limit` | number | no | 100 | Maximum entries |
| `pattern` | string | no | — | Glob pattern filter |
### search
| `skill` | string | yes | — | Skill name or path |
| `query` | string | yes | — | Search query |
| `limit` | number | no | 10 | Maximum results |
### stats
| `skill` | string | yes | — | Skill name or path |
| `group_by` | string | no | summary | Aggregation dimension: `summary`, `files`, `sections`, `commands`, `projects`, `errors`, `search` |
| `since` | string | no | — | Include accesses on or after (ISO 8601) |
| `until` | string | no | — | Include accesses on or before (ISO 8601) |
| `project` | string[] | no | — | Filter by project directory |
### sync (CLI-only)
| `skill` | string | no | — | Specific skill to sync |
| `project` | string | no | CWD | Project directory |
| `dry_run` | boolean | no | false | Preview without writing |
**Rationale for CLI-only commands:**
- **sync**: MCP servers run outside the sandbox and write directly to primary runtime locations. No fallback logs are created, so there is nothing to sync. See [RFC-0007:C-LOGGING](../rfc/RFC-0007.md#rfc-0007c-logging) for fallback mechanism.
- **mcp**: Starts the MCP server itself; not callable from within MCP.
## MCP Tool Naming
MCP tools use snake_case with `skc_` prefix:
| `skc init` | `skc_init` |
| `skc list` | `skc_list` |
| `skc build` | `skc_build` |
| `skc lint` | `skc_lint` |
| `skc outline` | `skc_outline` |
| `skc show` | `skc_show` |
| `skc open` | `skc_open` |
| `skc sources` | `skc_sources` |
| `skc search` | `skc_search` |
| `skc stats` | `skc_stats` |
*Since: v0.1.0*
### [RFC-0007:C-RESOLUTION] Skill Resolution (Normative) <a id="rfc-0007c-resolution"></a>
All commands that operate on skills accept a `<skill>` argument that identifies the target skill.
**Source directory resolution (first match wins):**
1. If `<skill>` resolves to a valid directory path containing `SKILL.md`, use it directly (CWD-relative or absolute). This means a local path takes precedence over a global skill with the same name.
2. If project config exists (`.skillc/config.toml` relative to CWD), check project source store using `<skill>` as a name
3. Check global source store (`~/.skillc/skills/<skill>/`) using `<skill>` as a name
4. Resolution failed. Exit with error per [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes):
- If a directory was found at any step but it lacks `SKILL.md`: emit **E010**
- Otherwise (no directory found at all): emit **E001**
**Runtime directory resolution (for logging):**
Derive `<skill-name>` from the resolved source directory's basename.
Resolve the runtime store using the same config precedence as storage layout (project config, then global config, then defaults).
The runtime directory is `<runtime-store>/<skill-name>/`.
If multiple source directories share the same basename within the same runtime store, they will share a log database; `skill_path` in the log distinguishes entries.
*Since: v0.1.0*
### [RFC-0007:C-LOGGING] Access Logging (Normative) <a id="rfc-0007c-logging"></a>
All commands that resolve skills MUST log access events for usage analytics.
**Log storage:**
Logs MUST be stored in a SQLite database at `.skillc-meta/logs.db` in the resolved runtime directory.
**Schema:**
The database MUST contain an `access_log` table with at minimum:
- `id` — Auto-incrementing primary key
- `timestamp` — RFC 3339 UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`)
- `run_id` — Session identifier
- `command` — Command name (the `skc` subcommand, e.g., `outline`, `show`, `open`, `search`, `build`, `stats`)
- `skill` — Skill name (directory basename)
- `skill_path` — Canonicalized absolute path to the resolved skill source directory
- `cwd` — Canonicalized absolute path of the current working directory when command was invoked
- `args` — JSON-encoded command arguments
- `error` — Error message if command failed (NULL on success)
Canonicalization MUST resolve `.` and `..` path segments and MUST resolve symlinks to their real paths.
**Run ID generation:**
If `SKC_RUN_ID` environment variable is set, use its value. Otherwise, generate a run ID in the format `YYYYMMDDTHHMMSSZ-<rand4>` where `<rand4>` is 4 random hex characters.
**Initialization:**
The command MUST attempt to create the runtime directory, `.skillc-meta/` subdirectory, database, and schema if they do not exist.
**Fallback logging (EAFP):**
The command MUST first attempt to write to the primary runtime directory. If the INSERT fails with a read-only error (e.g., sandboxed filesystem), the command MUST fall back to `<cwd>/.skillc/logs/<skill-name>/.skillc-meta/logs.db`. The fallback directory and database MUST be created if they do not exist.
If both primary and fallback locations fail, the command MUST emit a warning to stderr:
`warning: logging disabled; run 'skc sync' after session to merge logs`
**Stale fallback warning:**
If fallback logs exist for the current skill and the database file's mtime is older than 1 hour, the command SHOULD emit a warning to stderr:
`warning: stale local logs for '<skill>'; run 'skc sync' to upload`
This warning SHOULD be emitted at most once per command invocation (not per skill if multiple skills are accessed).
The command MUST continue execution regardless of logging success.
*Since: v0.1.0*
### [RFC-0007:C-SYNC] Sync Command (Normative) <a id="rfc-0007c-sync"></a>
**Syntax:** `skc sync [<skill>] [options]`
The sync command MUST move log entries from project-local fallback databases to the primary runtime log, then delete the local fallback.
**Source discovery:**
Scan `<cwd>/.skillc/logs/` for skill subdirectories containing `.skillc-meta/logs.db`. If `<skill>` is provided, sync only that skill's logs.
**Destination:**
The primary runtime directory per [RFC-0007:C-RESOLUTION](../rfc/RFC-0007.md#rfc-0007c-resolution). For global skills, this is typically `~/.skillc/runtime/<skill>/.skillc-meta/logs.db`.
**Behavior:**
1. For each discovered skill, copy all entries to the destination database
2. Skip entries that already exist (idempotent safety check)
3. After successful copy, delete the local fallback database directory
4. If destination is not writable (e.g., sandbox still active), emit error E041 and skip that skill
**Partial failure:**
If sync succeeds for skill A but fails for skill B, delete A's local logs and report B's error. Each skill is independent.
**Options:**
| `--project <path>` | Sync from specified project directory instead of CWD |
| `--dry-run` | Show what would be synced without writing or deleting |
**Output:**
```
Synced 47 entries for 'rust' (local logs removed)
Synced 12 entries for 'cuda' (local logs removed)
```
With `--dry-run`:
```
Would sync 47 entries for 'rust'
Would sync 12 entries for 'cuda'
```
If no local logs exist:
```
No local logs to sync
```
**Exit codes:**
- 0: Success (including "nothing to sync")
- 1: Error (partial or complete failure). See [RFC-0005:C-CODES](../rfc/RFC-0005.md#rfc-0005c-codes) for error codes E040–E042.
*Since: v0.1.0*
### [RFC-0007:C-LIST] List Command (Normative) <a id="rfc-0007c-list"></a>
**Syntax:** `skc list [options]`
The list command MUST enumerate all skillc-managed skills from source stores.
## Discovery
The command MUST discover skills from these locations in order:
1. **Project-local source store**: Recursive-up search for `.skillc/skills/` directories
2. **Global source store**: `~/.skillc/skills/`
A valid skill is a directory containing a `SKILL.md` file with valid frontmatter.
## Status Detection
### Default (Fast Mode)
Without `--check-obsolete`, status detection is fast:
| `normal` | Runtime directory exists with valid manifest.json |
| `not-built` | No runtime directory or no manifest.json |
### With --check-obsolete (Hash Comparison)
When `--check-obsolete` is provided, the command performs expensive source hash comparison:
| `normal` | Runtime exists and source hash matches manifest |
| `not-built` | No runtime directory or no manifest.json |
| `obsolete` | Runtime exists but source hash differs from manifest |
## Output Format
### Text Output (CLI default)
```
$ skc list
SKILL SCOPE STATUS
my-skill project normal
cuda global not-built
```
When `--verbose` is provided, include paths:
```
$ skc list --verbose
SKILL SCOPE STATUS SOURCE
my-skill project normal .skillc/skills/my-skill
cuda global not-built ~/.skillc/skills/cuda
```
### JSON Output (MCP default)
```json
{
"skills": [
{
"name": "my-skill",
"scope": "project",
"status": "normal",
"source_path": "/path/to/.skillc/skills/my-skill",
"runtime_path": "/path/to/.skillc/runtime/my-skill"
}
],
"total": 1,
"filtered": 1
}
```
## Filtering
| `--scope` | `project\|global\|all` | `all` | Filter by skill scope |
| `--status` | `normal\|not-built\|obsolete\|all` | `all` | Filter by build status |
| `--limit` | number | unlimited | Maximum skills to return |
| `--pattern` | string | — | Filter by skill name (glob pattern) |
| `--check-obsolete` | boolean | false | Enable hash comparison for obsolete detection |
## Ordering
Skills MUST be ordered by:
1. Scope: project before global
2. Name: alphabetical within scope
## Error Handling
- If no skills are found, output an empty list (not an error)
- If a skill directory exists but `SKILL.md` is invalid, skip with warning
*Since: v0.1.0*
---
## 3. MCP Interface
### [RFC-0007:C-MCP-OVERVIEW] MCP Interface Overview (Informative) <a id="rfc-0007c-mcp-overview"></a>
The MCP (Model Context Protocol) interface provides structured access to skillc functionality for AI agents. Per [ADR-0003](../adr/ADR-0003.md), MCP is the recommended interface for agents because:
1. **No sandbox restrictions:** MCP servers run outside the IDE sandbox, enabling writes to global directories
2. **Structured I/O:** JSON input/output eliminates text parsing errors
3. **Native integration:** MCP is the designed protocol for agent tools
4. **Reduced latency:** No shell process spawn per command
The MCP interface mirrors CLI functionality. Each CLI command has a corresponding MCP tool with equivalent behavior but structured data exchange.
**Architecture:**
```
Human users: Terminal → skc CLI → skillc core
AI agents: MCP client → skillc MCP server → skillc core
```
*Since: v0.1.0*
### [RFC-0007:C-MCP-SERVER] MCP Server (Normative) <a id="rfc-0007c-mcp-server"></a>
**Syntax:** `skc mcp`
The MCP server command MUST start a long-running process that speaks the MCP protocol over stdio.
**Protocol:**
The server MUST implement the MCP stdio transport:
- Read JSON-RPC messages from stdin
- Write JSON-RPC messages to stdout
- Diagnostic output (if any) MUST go to stderr
**Server info:**
The server MUST respond to `initialize` with:
- `name`: `"skillc"`
- `version`: The skillc version string
**Tool discovery:**
The server MUST respond to `tools/list` with the MCP-enabled tools defined in [RFC-0007:C-COMMANDS](../rfc/RFC-0007.md#rfc-0007c-commands).
**Configuration:**
The MCP server is configured in the agent's MCP settings:
```json
{
"mcpServers": {
"skillc": {
"command": "skc",
"args": ["mcp"]
}
}
}
```
**Logging:**
All tool invocations MUST be logged per [RFC-0007:C-LOGGING](../rfc/RFC-0007.md#rfc-0007c-logging). Since the MCP server runs outside the sandbox, logging SHOULD write directly to the primary runtime location (no fallback needed).
*Since: v0.1.0*
---
## Changelog
### v0.1.0 (2026-01-30)
Initial release