Skill Best Practices & Usage Rules
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The cxs skill is a specialized toolset designed for AI agents to interact with local Codex session logs via a progressive retrieval command-line interface (CLI). Unlike standard search tools, the cxs skill emphasizes a "locate first, read later" philosophy, moving from broad session discovery to granular context extraction without overwhelming the agent with excessive raw data.
The scope of this skill is strictly limited to archaeological retrieval of local configurations, historical discussions, and past project contexts. It is intentionally not intended for real-time code search within a repository or daily summary tasks, which are handled by other specialized tools.
Sources: skill-packages/cxs/SKILL.md:1-12, README.md:1-12
Core Retrieval Workflow
The fundamental architecture of the cxs skill follows a strict progressive chain: status -> ensure coverage -> find/list -> read-range -> read-page. This prevents the "cold start" problem of reading massive JSONL files by ensuring the index is ready and the search is scoped before any content is returned.
The diagram above illustrates the standard execution flow required for agents to maintain data integrity and performance.
Sources: AGENTS.md:16-20, skill-packages/cxs/SKILL.md:46-52
1. Status and Coverage Inspection
Before performing any search, an agent must check the current source inventory and index state. The status command identifies available session groups and provides a recommendedAction.
- Key Logic: If
requestedCoverage.recommendedActionis"sync", the agent must synchronize before querying. If it is"query", the existing index is sufficient. - Rule:
statusandstatus --selectorare read-only and do not trigger implicit syncs.
Sources: AGENTS.md:21-25, skill-packages/cxs/references/cli-surface.md:19-27
2. Synchronization Rules
sync --selector is the unique entry point for building coverage.
- Strictness: By default,
syncis strict. If a file fails to parse, it exits with an error and does not commit coverage unless--best-effortis specified. - Coverage Inheritance: A fresh
allroot coverage record can satisfy narrowercwdordate_rangeselectors under the same root.
Sources: AGENTS.md:26-28, README.md:94-105
3. Progressive Reading
Once a session is identified via find or list, agents should use read-range to expand local context around hit sequences. read-page is reserved for instances where the local window is insufficient or when the match source is "session-level" (no specific message sequence).
Sources: skill-packages/cxs/references/progressive-workflow.md:1-10
Command Usage and Patterns
Agents must adhere to specific command patterns based on the user's intent to ensure the most relevant historical data is retrieved.
| Scenario | Preferred Command | Logic / Reason |
|---|---|---|
| Keyword Search | find <query> | Defaults to relevance ranking. |
| Chronological Search | find <query> --sort ended | Essential for "latest/recent" keyword queries. |
| Project Listing | list --selector <cwd_json> | Better than find when the user gives a repo path but no keywords. |
| Context Expansion | read-range --seq <n> | Targeted reading around a specific message anchor. |
| Self-Hit Exclusion | --exclude-session <uuid> | Used to prevent the current conversation from appearing in results. |
Sources: skill-packages/cxs/SKILL.md:31-41, skill-packages/cxs/references/cli-surface.md:65-79
Handling CJK and Zero-Token Queries
Current tokenization strategies use overlapping bigrams for CJK (Chinese, Japanese, Korean) characters. Single characters do not form valid FTS terms.
- Fallback: If a query contains CJK but tokens are empty, the system falls back to a bounded
LIKEscan. - Best Practice: Agents should use at least two-character Chinese words or combine them with English identifiers.
Sources: AGENTS.md:32-33, skill-packages/cxs/references/failure-cookbook.md:11-12
Failure Recovery & Cookbook
The following sequence diagram represents the agent's interaction when encountering common errors like an unavailable index.
Common Error Resolutions
- Index Unavailable: Run
statusto find the root, thensync --selector. - Database Locked: Retry the command; this is typically a transient SQLite state.
- Zero Results: Check coverage status for the target selector; if fresh, refine keywords or use
list. - Selector Required:
synccommands must always provide an explicit JSON selector; there is no default range.
Sources: skill-packages/cxs/references/failure-cookbook.md:1-12
Post-Usage Evaluation
After every cxs operation, the agent should perform a "Lightweight Self-Evaluation" (自评). This is a critical feedback loop for the Dogfooding process.
Evaluation Categories
- Good: Results directly supported the answer.
- Query-Refine: Initial search failed, but succeeded after refining keywords or sorts.
- Coverage-Issue: Problem was due to missing or stale index (requires
sync). - Skill-Guidance-Issue: Agent failed to follow rules (e.g., fabricated a sequence number).
- Dogfood-Candidate: Reproducible ranking or recall issues that should be reported to the user.
Rule for Dogfooding: If a case is a dogfood-candidate, the agent must provide a hint to the user: This looks like a cxs dogfood candidate: <reason>. Say "$cxs-dogfood record this" to capture it.
Sources: skill-packages/cxs/SKILL.md:58-75, AGENTS.md:58-70
Conclusion
The cxs skill best practices center on a structured, coverage-first approach to retrieval. By following the progressive workflow—validating coverage via status, synchronizing only when necessary, and using targeted reading commands—agents can efficiently navigate large volumes of historical Codex sessions. Adhering to these rules ensures that the retrieval engine remains a reliable "archaeology" tool for local project and configuration history.