COMPASS Skills: A Local State Layer for Long-Running AI Agent Work

What COMPASS Skills Solves and Who It Is For

The repository addresses a specific failure mode: AI agents lose state when a conversation ends or when a task grows too complex for the model to hold in context. The README names five kinds of state that long-running agent work needs: user context, project context, goal context, pause context, and handoff context. COMPASS Skills packages those into nine SKILL.md files that an agent can invoke with a dollar-sign command like $task-clarifier or $pause-and-resume. The intended user is someone who runs Claude Code or Codex over multiple sessions on a single repository and wants the agent to remember preferences, task dependencies, and safe stopping points without replaying an entire transcript. It is not for casual one-shot queries; the design assumes sustained, multi-step work where context loss is the main cost.

The Nine Skills and How They Divide Labor

The repository ships five runtime collaboration skills, two run-history skill-engineering skills, one academic humanization skill, and one local hiring-support skill. The runtime set is the core: task-clarifier aligns goals and acceptance criteria before ambiguous or risky work; task-forest maintains a repo-local task graph with dependencies and progress; pause-and-resume stops at a safe boundary and resumes from a checkpoint in the same conversation; session-handoff-prompt compresses the current state into a paste-ready prompt for a new conversation; user-profile-keeper stores a local, auditable collaboration profile. The run-history pair is meta: run-history-skill-builder turns completed workflows into new skill packages, and run-history-skill-upgrader uses session evidence to propose upgrades to existing skills, applying changes only after explicit approval. The other two skills, academic-humanizer and assess-interview-candidate, are narrower and sit apart from the state-management theme. That mix gives the repository a split personality: five skills form a coherent system, while the other four are standalone utilities that happen to live in the same repo.

How the State Flows Between Skills

The README describes a deliberate data flow. task-clarifier is the entry gate: it identifies user-owned decisions, asks one to three focused questions with recommended answers, and only then proceeds to search or execute. task-forest records the structure of long-running work, including why a task exists and what remains unresolved. pause-and-resume reads that structure to find a safe stopping point and records what must and must not be repeated, but it creates no file solely for pausing. session-handoff-prompt reads task-forest as structured context but never modifies it, turning the conversation and workspace evidence into a continuation prompt. user-profile-keeper stores preferences locally, and the README stresses that current files, logs, and user-provided context remain the authority, with secrets kept out of the profile. This separation of read and write roles is the key architectural choice: task-forest is the shared source of truth, while the other skills either write to it or read from it without mutating it. That keeps the system auditable, because each skill has a defined scope of influence.

Installation and Invocation: Real Commands

Installation goes through the skills command-line tool. To list available skills before installing, the README gives: npx skills add dongshuyan/compass-skills --list. To install all skills for Claude Code, run npx skills add dongshuyan/compass-skills --skill '*' -a claude-code. For both Codex and Claude Code, the command is npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code. After installation, you invoke a skill directly in an AI conversation by typing its name with a dollar sign, for example $task-clarifier or $session-handoff-prompt. There is also a manual path: copy the nine folders under skills/ into the agent's local skills directory, keeping the references/, scripts/, assets/, evals/, and agents/ subdirectories intact. The manual path matters because it implies the skills are not single-file prompts; they carry supporting material that must survive the copy. The README points to an external tutorial at dongshuyan.com for writing your own skill ecosystem, which suggests the project wants users to extend it, not just consume it.

A Genuine Limitation: Single-Conversation Assumption and Manual Overhead

The most obvious limitation is that pause-and-resume and session-handoff-prompt assume a specific workflow. pause-and-resume explicitly works only when the same AI conversation remains available; session-handoff-prompt is for when work must move to a fresh conversation. That is a real constraint, because many agent workflows involve parallel conversations or a mix of tools. The README says to choose one based on whether the conversation will remain available, which puts the burden on the user to make that call correctly. Another limitation is that task-forest is repo-local. It survives AI conversation boundaries, but not repository boundaries. If your work spans multiple repos, the task graph will not follow. The user-profile-keeper also requires manual inspection and correction; the README calls it auditable and correctable, which means it is not automatic. You have to read the profile and fix errors yourself. For a system that claims to reduce context loss, the manual overhead is a trade-off, not a free win.

The Meta-Skills: Self-Evolution With a Brake

The run-history pair is the most interesting part of the project. run-history-skill-builder turns a completed or repeatedly refined workflow into a new skill package or a plan-only design. If the request is really about changing an existing skill, it hands the job off instead of editing that skill directly. run-history-skill-upgrader goes further: it automatically reads session evidence, including encountered difficulties, validation results, and user feedback, and turns that into an upgrade plan for an existing skill. The README emphasizes that it applies changes only after explicit approval. That approval gate is the crucial safety mechanism; without it, the system would be editing its own instructions without human oversight. The design forms what the README calls the simplest controlled self-evolution loop. This is a genuinely different approach from static skill packages, and it is the reason to watch this project. But the loop depends on the quality of the session evidence, and the README does not specify how the upgrader validates that evidence beyond user feedback. That is a gap worth probing before relying on it.

Alternatives and the Difference in Approach

The closest alternative is the native context management built into agent frameworks like Claude Code's own memory or Codex's session persistence. Those tools keep conversation history but do not structure it into a task graph or a user profile. COMPASS Skills is different because it externalizes state into files that you can inspect and correct. Another alternative is a project management tool like Linear or a plain markdown file that you update manually. That approach gives you full control but no agent integration; COMPASS Skills puts the state in a format the agent can read and write. The key difference is that COMPASS Skills makes the state machine explicit: a task forest, a pause checkpoint, a handoff prompt. Manual notes do not enforce a safe stopping point or a clarification gate. The trade-off is that you adopt a specific skill format and the skills CLI, which ties you to the ecosystem. If you want a lighter touch, you could write your own prompts, but you would lose the structured read-write separation that this project provides.

Maintenance, License, and Upgrade Cost

The repository is under the MIT license, which means you can use, modify, and redistribute it with few restrictions, but you should check the LICENSE file for exact terms. The project has seen three releases in a week: v0.1.0 on 2026-06-15, v0.2.0 on 2026-06-16, and v0.3.0 on 2026-06-21. That rapid cadence suggests active development but also means the skill interfaces may change between versions. The upgrade cost is not trivial. If you install manually, you must keep the subdirectories intact, and if you upgrade, you need to re-copy or re-run the npx command. The run-history-skill-upgrader is designed to automate skill evolution, but it requires explicit approval, so you still have to review proposed changes. The README does not mention a migration path between versions, so you should snapshot your skills directory before upgrading. The maintenance burden is on you to keep the task forest and profile current; the tools only help if you actually invoke them.

Editorial conclusion

Adopt COMPASS Skills if you run long, multi-session AI agent work in Claude Code or Codex and need a auditable, local way to preserve user context, task structure, and safe pause points. Do not adopt it if you work in a single short conversation, need cross-repository state, or cannot tolerate the overhead of maintaining a task forest and profile. Before adopting, verify that your agent's skills directory supports the references/, scripts/, assets/, evals/, and agents/ subdirectories, and test the pause-and-resume flow with a real interrupted task to confirm the checkpoint survives a conversation restart.

Official sources

1. Official README
2. Project repository
3. Release notes