RFC-0007: CLI Reference

Version: 0.1.0 | Status: normative | Phase: test

1. Summary

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

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 — Skill Compilation (build command behavioral spec)
• RFC-0002 — Gateway Protocol (outline, show, open, sources behavioral specs)
• RFC-0003 — Usage Analytics (stats command behavioral spec)
• RFC-0004 — Search Protocol (search command behavioral spec)
• RFC-0005 — Error Code Registry (canonical error codes)
• RFC-0006 — 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)

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

Parameter Definitions

init

list

See RFC-0007:C-LIST for full specification.

build

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.

lint

outline

show

open

sources

search

stats

sync (CLI-only)

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

Since: v0.1.0

[RFC-0007:C-RESOLUTION] Skill Resolution (Normative)

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

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)

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

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 for error codes E040–E042.

Since: v0.1.0

[RFC-0007:C-LIST] List Command (Normative)

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:

With –check-obsolete (Hash Comparison)

When --check-obsolete is provided, the command performs expensive source hash comparison:

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)

{
  "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

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)

The MCP (Model Context Protocol) interface provides structured access to skillc functionality for AI agents. Per ADR-0003, 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)

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.

Configuration:

The MCP server is configured in the agent’s MCP settings:

{
  "mcpServers": {
    "skillc": {
      "command": "skc",
      "args": ["mcp"]
    }
  }
}

Logging:

All tool invocations MUST be logged per RFC-0007:C-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