COMPASS Skills: a local state layer for long-running AI agent work

What COMPASS Skills is for, and who it is not for

The README frames the problem as state loss. Long agent sessions accumulate five kinds of context: who the user is, where the current request sits in the project, how the task relates to the original goal, where a safe stopping point is, and what a fresh conversation would need to continue. All of that normally lives in the transcript, and the transcript is the one artifact that does not survive a new conversation.

COMPASS Skills answers with nine local skills, each a folder under skills/ containing a SKILL.md. Five are runtime collaboration skills, two are run-history skill-engineering skills, one is an academic prose editor, and one turns an authorized resume plus job description into an interviewer report. The intended user is someone doing multi-session agent work who is willing to keep the state in files they can open. It is not a hosted service, and the README describes no server, database or synchronization layer.

That narrowness is a design choice worth naming. The skills are not a framework you import. They are instruction packages the agent loads, and the durable artifacts they produce are ordinary files in the repository.

How the five runtime skills divide the state

The split is by lifetime, not by topic. task-clarifier is the entry gate: it identifies the decisions the user owns, asks one to three focused questions with recommended answers, confirms shared understanding, and only then allows search or execution. It is meant for ambiguous, high-cost, high-risk, evidence-sensitive or externally visible work, which is a narrow trigger and deliberately so.

task-forest owns the slow state. It maintains a repo-local task graph recording why a task exists, what it depends on, how far it got, what deviated and what remains unresolved. Because the graph is repo-local, it survives conversation boundaries, and session-handoff-prompt can read it as structured context. The README is explicit that the handoff skill never modifies the forest, which keeps one writer per artifact.

The two pause skills are a genuine fork rather than a duplicate. pause-and-resume stops unfinished work at the nearest safe boundary, records what must and must not be repeated, and continues in the same conversation. The README notes it creates no file solely for pausing. session-handoff-prompt compresses the conversation, explicit transcripts, workspace evidence and optional task-forest exports into a paste-ready prompt for a new conversation. Use the first when the conversation stays alive; use the second when it cannot.

user-profile-keeper holds collaboration preferences locally: communication style, risk boundaries and recurring omissions. The README states two limits that matter. Current files, logs and user-provided context remain the authority over the profile, and secrets stay out of it. A stale profile therefore cannot silently override what is actually on disk.

Installing COMPASS Skills and running a first task

Installation goes through the skills CLI rather than pip. List what the repository ships before committing to anything:

npx skills add dongshuyan/compass-skills --list

The README shows this as the way to see the available skills, so the output should enumerate the nine SKILL.md packages. Installing all of them for Claude Code uses a wildcard:

npx skills add dongshuyan/compass-skills --skill '*' -a claude-code

The -a flag takes the agent name and can be repeated. The README gives this example for installing into both Codex and Claude Code at once:

npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code

Manual installation is also documented: copy the nine folders under skills/ into the agent's local skills directory and keep their references/, scripts/, assets/, evals/ and agents/ subdirectories intact. Dropping a subdirectory is the obvious way to break a skill, since the SKILL.md may reference those paths.

After installation, skills are invoked by name inside the conversation. The README lists the invocation strings:

$task-clarifier
$task-forest
$pause-and-resume
$session-handoff-prompt
$user-profile-keeper
$run-history-skill-builder
$run-history-skill-upgrader
$academic-humanizer
$assess-interview-candidate

A sensible first run is to invoke $task-clarifier on a request you would normally start immediately. The README says it should surface the user-owned decisions and ask one to three questions with recommended answers before any searching or execution. If it starts working without asking, the skill is not doing what the documentation describes, and that is worth investigating before you rely on the rest.

The run-history pair and the approval boundary

run-history-skill-builder and run-history-skill-upgrader are the meta layer, and they are the part most likely to be misused. The builder turns a completed or repeatedly refined workflow into a new skill package, or into a plan-only design when you do not want files written. The README adds a routing rule: if the request is really about changing an existing skill, the builder hands the job off rather than editing that skill itself.

The upgrader is the more interesting one. It reads session evidence from real execution, difficulties encountered and resolved, validation results and user feedback, and turns that into an upgrade plan for an existing skill. The README calls this the simplest controlled self-evolution loop and states that changes are applied only after explicit approval.

That approval gate is the whole safety argument. An agent that rewrites its own instructions from a single session's evidence can encode a one-off workaround as a permanent rule. Requiring approval keeps a human at the point where a session artifact becomes a durable instruction. If you run the upgrader in an unattended loop, you have removed the only control the design provides. The README does not describe an automatic rollback of an applied upgrade, so the review step before approval is the rollback.

academic-humanizer and assess-interview-candidate sit apart

Two skills do not fit the state-management story and are best treated as separate tools that happen to ship in the same repository. academic-humanizer revises English and Chinese academic prose by removing formulaic AI-like patterns and restoring a natural scholarly voice. The README states that it preserves claims, evidence strength and logical relations. That is a specific constraint: the skill is scoped to style, not to argument, and any edit that changes what a sentence asserts is outside its stated remit.

assess-interview-candidate is the most constrained of the nine. It turns an authorized resume and job description into an evidence layer and a three-part offline interviewer report, with locally sanitized resume portraits and bounded timeline-age estimates kept outside scoring. The word authorized matters here, and so does offline. The README describes no upload path, and the timeline-age handling is explicitly excluded from the score rather than folded into it.

If you need neither academic prose editing nor hiring support, install only the skills you need. The README recommends exactly that for multi-skill repositories, and the wildcard install is a convenience, not a requirement.

Limitations, and when COMPASS Skills is the wrong tool

The first limitation is boundary discipline. pause-and-resume only works when the same conversation remains available, and session-handoff-prompt is the substitute when it does not. Picking the wrong one loses the thing you were trying to preserve. The README states the distinction plainly, but the choice is still yours to make at the moment work stops, which is usually the worst moment to be making it.

The second is that everything is local and file-based. There is no synchronization between machines, no shared team state, and no dashboard. If two engineers are working the same problem in separate repositories, their task forests are separate artifacts. Nothing in the README suggests otherwise.

The third is scope creep. Nine skills installed at once means nine sets of instructions competing for the agent's attention, and the README's own advice is to install only what you need. The academic and hiring skills are the clearest cases for leaving out.

Finally, the repository does not document rollback for applied skill upgrades, and the README does not describe what happens when a task forest and a handoff prompt disagree. The handoff skill reads the forest and does not modify it, so the forest is the reference, but conflict handling is not spelled out. If your workflow depends on that answer, verify it before you depend on it.

Maintenance, licence and the cost of upgrading

The last push to the repository was on 2026-06-21, which is the same date as the v0.3.0 release. The three releases are close together: v0.1.0 on 2026-06-15, v0.2.0 on 2026-06-16, and v0.3.0 on 2026-06-21. That is a burst of activity rather than a long steady cadence, and the repository is not archived. Treat the release history as the evidence for how fast the skill set is changing, not as a promise about the next release.

The upgrade cost is mostly re-reading SKILL.md files. Because skills are instruction packages rather than a library, a version bump can change how the agent behaves without changing any import in your code. If you have customized a skill locally, an upgrade can overwrite that customization, and the README does not describe a merge path for local edits. Forking or copying a skill under a new name is the obvious workaround, at the cost of tracking upstream changes yourself.

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a factual description of the licence text, not legal advice; if your organization has specific obligations around bundled third-party notices, check the LICENSE file and your own policy.

Editorial conclusion

Adopt COMPASS Skills if you run long, multi-session agent work in Claude Code or Codex and want the state on disk where you can read and correct it. Skip it if your work fits in one conversation, or if you need a hosted dashboard, cross-user sync or a scheduler: the README describes local skills only, and no server component appears in the repository. Before installing, run the list command and confirm that nine skills is the count you want, then read the SKILL.md of task-clarifier and pause-and-resume, because those two define the boundary behaviour the other skills assume.

Frequently asked questions

Official sources

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