Agent Skill Package Overview
Relevant source files
The following files were used as context for generating this wiki page:
The cxs Agent Skill Package is a distributable set of instructions and tools designed to enable AI agents (such as Codex or Claude Code) to interact with local Codex session logs effectively. It acts as a retrieval engine, allowing agents to search through historical conversations to answer questions about past configurations, discussions, or project states. The skill emphasizes a "progressive retrieval" philosophy: first locating the correct session, then expanding the local context, and only reading full pages when necessary.
Sources: README.md:3-6, skill-packages/cxs/SKILL.md:1-5, AGENTS.md:58-61
Architecture and Core Workflow
The skill package is structured around a non-GUI, progressive workflow. It treats the cxs CLI as its primary execution backend. The architecture follows a strict chain of commands to ensure data freshness and minimize token consumption during retrieval.
Progressive Retrieval Flow
The standard operational sequence for the agent is:
- Status: Check the execution context and index coverage.
- Ensure Coverage: Verify if the required data range is indexed and fresh; synchronize if needed.
- Find/List: Perform full-text search or list sessions based on metadata (CWD, date).
- Read-Range: Expand context around specific matched messages.
- Read-Page: Perform full-session reading only as a final resort.
Sources: README.md:10-12, skill-packages/cxs/references/progressive-workflow.md:3-9, AGENTS.md:7-13
Workflow Visualization
The following diagram illustrates the decision logic an agent must follow when processing a retrieval request:
The diagram shows the transition from initial status checks to final answer generation, emphasizing the coverage-first requirement.
Sources: skill-packages/cxs/SKILL.md:46-52, skill-packages/cxs/references/progressive-workflow.md:3-15
Installation and Environment
The skill package distinguishes between the CLI binary and the agent-specific skill definition.
| Component | Installation Command | Purpose |
|---|---|---|
| cxs CLI | npm i -g @act0r/cxs | The underlying retrieval engine and SQLite manager. |
| Agent Skill | npx skills add catoncat/cxs --full-depth --skill cxs -g -a codex -y | The instruction set and tool definitions for the agent runtime. |
Sources: README.md:27-33, skill-packages/cxs/SKILL.md:12-24
Environment Configuration
The skill prioritizes the CXS_BIN environment variable. If not set, it falls back to the cxs binary in the system PATH.
Sources: AGENTS.md:65-68, skill-packages/cxs/SKILL.md:19-21
CLI Command Interface for Agents
The skill instructs agents to use specific CLI commands with the --json flag to receive structured data for processing.
Primary Commands
status: Reports source inventory and coverage. It scans raw metadata but does not write to the index.sync --selector <json>: The only command that modifies the SQLite index. It requires an explicit selector.find <query>: Searches indexed sessions. Supports--sort endedfor chronological relevance and--exclude-sessionto avoid self-hits.read-range <uuid>: Anchors to a specific message (--seq) or query (--query) to provide local context window.
Sources: README.md:49-57, skill-packages/cxs/references/cli-surface.md:11-20, AGENTS.md:14-18
Selector Mechanism
Selectors are used to constrain both synchronization and search. They are critical for managing large session histories.
type Selector =
| { kind: "all"; root: string }
| { kind: "date_range"; root: string; fromDate: string; toDate: string }
| { kind: "cwd"; root: string; cwd: string }
| { kind: "cwd_date_range"; root: string; cwd: string; fromDate: string; toDate: string };
Sources: src/types.ts:31-36, README.md:61-68
Data Models and Response Schemas
When an agent executes a search, it receives a FindResult object. The matchSource field is particularly important for determining the next retrieval step.
| Field | Type | Description |
|---|---|---|
matchSource | "message" | "session" | Indicates if the hit was in a specific message or session-level metadata. |
matchSeq | number | null | The sequence number for message hits; null for session-level hits. |
summaryText | string | A generated summary of the session. |
matchRole | string | The role (user, assistant, or session) that triggered the hit. |
Sources: src/types.ts:133-146, skill-packages/cxs/references/cli-surface.md:85-92
Sequence Diagram: Context Retrieval
This diagram shows the interaction between the Agent and the CLI when expanding context:
Failure Handling and Self-Evaluation
The skill package includes a "Failure Cookbook" to help agents resolve common issues like missing indexes or stale coverage.
Common Error Codes
index_unavailable: The index has not been created. Action: Runsync --selector.selector_required:syncwas called without a scope. Action: Construct a valid JSON selector.recommendedAction: "sync": The coverage for the requested selector is missing or stale.
Sources: skill-packages/cxs/references/failure-cookbook.md:3-15, skill-packages/cxs/references/cli-surface.md:9-12
Dogfooding and Evaluation
The skill guides agents to perform light-weight self-evaluation after each use. If a retrieval is unsuccessful (e.g., recall miss or bad ranking), the agent suggests recording the case as a dogfood-candidate. This triggers a separate workflow for capturing "golden" test cases for future engineering improvements.
Sources: AGENTS.md:87-98, skill-packages/cxs/SKILL.md:65-80
Conclusion
The Agent Skill Package for cxs provides a robust, coverage-centric framework for local session retrieval. By enforcing a workflow of status -> sync -> find -> read, it ensures technical accuracy and efficiency. It is designed not just for search, but as a "personal setup archaeology" tool, enabling agents to leverage historical context for complex本机 (local machine) configuration tasks.
Sources: skill-packages/cxs/SKILL.md:3-10, AGENTS.md:120-123