RFC-0003: Usage Analytics

Version: 0.1.0 | Status: normative | Phase: test

1. Summary

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

Usage analytics enables skill authors to understand how agents interact with their skills.

The analytics system is designed as a data layer with multiple front-end consumers:

CLI commands for quick insights
JSON output for scripts and automation
Future: web API and dashboard

Analytics queries the access logs created by RFC-0007:C-LOGGING and aggregates usage data.

Commands:

skc stats <skill> — Show usage summary
skc stats <skill> --group-by <type> — Run specific aggregation
skc stats <skill> --format json — Machine-readable output

Since: v0.1.0

2. Specification

[RFC-0003:C-QUERIES] Query Types (Normative)

The analytics system MUST support the following query types:

summary — Overview statistics Returns total access count, unique sections accessed, unique files accessed, error count, and date range of data.

sections — Section access breakdown Returns a list of sections ordered by access count (descending). Ties MUST be ordered by file path, then section heading, both ascending. Each entry includes the section heading text, file path, and access count.

files — File access breakdown Returns a list of files ordered by access count (descending). Ties MUST be ordered by file path ascending. Each entry includes the file path and access count.

commands — Command type breakdown Returns access counts grouped by command type. All logged commands appear as keys. Known command types include: outline, show, open, search, build, stats. Additional command types (from future versions) MUST be included as extra keys.

projects — Project/CWD breakdown Returns access counts grouped by calling directory (CWD). Each entry includes the directory path and access count.

errors — Failed lookups Returns a list of failed access attempts. Each entry includes the requested target, command type, error message, and count.

search — Search query breakdown Returns a list of search queries ordered by frequency (descending). Ties MUST be ordered by query text ascending. Each entry includes the query string and count. This enables understanding which search terms agents use most frequently.

The default query type MUST be summary.

Since: v0.1.0

[RFC-0003:C-FILTERS] Query Filters (Normative)

All queries MUST support the following filters:

Time range filters:

--since <datetime> — Include only accesses on or after this timestamp
--until <datetime> — Include only accesses on or before this timestamp

Timestamps MUST be parsed as RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ) or date-only format (YYYY-MM-DD, interpreted as start of day UTC). Logged access timestamps MUST be stored in UTC.

If no time filters are provided, all available data MUST be included.

Project filter:

--project <path> — Include only accesses where CWD matches or is a subdirectory of the given path

The path MUST be matched as a prefix after canonicalization. Canonicalization MUST resolve . and .. path segments and MUST resolve symlinks to their real paths. Matching MUST use the canonicalized absolute paths for both the filter and the logged CWD. For example, --project /Users/me/webapp matches CWDs like /Users/me/webapp, /Users/me/webapp/src, etc.

Multiple --project flags MAY be provided; accesses matching ANY of the paths MUST be included (OR logic).

Filter application: Filters MUST be applied before aggregation. The response schema MUST include the applied filters in the filters field.

Since: v0.1.0

[RFC-0003:C-SCHEMA] Response Schema (Normative)

All analytics responses MUST conform to a JSON schema for interoperability with multiple front-ends.

Root response structure:

{
  "skill": "<skill-name>",
  "skill_path": "<absolute-source-path>",
  "query": "<query-type>",
  "filters": {
    "since": "<datetime-or-null>",
    "until": "<datetime-or-null>",
    "projects": ["<path>", ...]
  },
  "period": {
    "start": "<earliest-access-timestamp>",
    "end": "<latest-access-timestamp>"
  },
  "data": { ... }
}

Query-specific data structures:

summary:

{
  "total_accesses": 150,
  "unique_sections": 8,
  "unique_files": 3,
  "error_count": 5
}

sections:

[
  {"section": "Getting Started", "file": "SKILL.md", "count": 42},
  {"section": "API Reference", "file": "SKILL.md", "count": 35}
]

files:

[
  {"file": "SKILL.md", "count": 100},
  {"file": "docs/advanced.md", "count": 25}
]

commands:

{
  "outline": 50,
  "show": 80,
  "open": 20,
  "search": 45,
  "build": 10
}

projects:

[
  {"project": "/Users/me/webapp", "count": 75},
  {"project": "/Users/me/cli-tool", "count": 25}
]

errors:

[
  {"target": "NonExistentSection", "command": "show", "error": "Section not found", "count": 5}
]

search:

[
  {"query": "authentication", "count": 25},
  {"query": "error handling", "count": 18},
  {"query": "api", "count": 12}
]

The JSON output MUST be valid JSON. Field order is not significant.

Since: v0.1.0

[RFC-0003:C-CLI] CLI Commands (Normative)

Syntax: skc stats <skill> [options]

The stats command MUST query the access log for the specified skill and display usage analytics.

Options:

--group-by <type> — Aggregation dimension (default: summary) Valid values: summary, sections, files, commands, projects, errors

--format <format> — Output format (default: text) Valid values: text, json

--since <datetime> — Filter: include accesses on or after this time

--until <datetime> — Filter: include accesses on or before this time

--project <path> — Filter: include accesses from this project directory (may be repeated)

Skill resolution: The <skill> argument MUST be resolved using the same logic as RFC-0007:C-RESOLUTION.

Log database location: The command MUST read from .skillc-meta/logs.db in the resolved runtime directory (per RFC-0007:C-LOGGING).

No data: If the log database does not exist or contains no matching records, the command MUST return an empty result (not an error). For summary, this means all counts are zero.

Text output: When --format text (default), the command MUST produce human-readable output suitable for terminal display. The exact format is implementation-defined but MUST convey the same information as the JSON schema.

Exit codes:

0: Success (including empty results)
1: Error. See RFC-0003:C-ERRORS for error codes (E001/E010 for skill resolution, E030/E031 for invalid query/filter, E100 for invalid options).

Since: v0.1.0

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

All analytics 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. This RFC uses:

Condition	Error Code
Skill resolution failed	E001 or E010
Invalid query type	E030
Invalid filter	E031
Invalid CLI option	E100

Usage:

E001/E010: Skill resolution failed per RFC-0007:C-RESOLUTION. See RFC-0005:C-CODES for when to use each.
E030: --query value is not one of: summary, sections, files, commands, projects, errors
E031: --since, --until, or --project value is malformed
E100: Unknown flag, missing required value, or other CLI parsing failure

Note: Empty results (no matching log entries) are NOT errors. The command MUST return an empty result set with exit code 0.

Since: v0.1.0

Changelog

v0.1.0 (2026-01-30)

Initial release

Keyboard shortcuts

skillc