Ever sent your AI agent on a multi-session mission and come back to find it forgot what it was doing? Yeah, been there. But long-running agent work is great only until your assistant loses the plot somewhere around session three. So you explain the project context again, re-establish the goal, and hope it doesn’t drift off into some unrelated tangent halfway through.
That’s exactly the problem COMPASS Skills aims to fix — and honestly, it’s the first tool I’ve seen that treats this as a first-class problem. And 204 stars in 2 days on GitHub says I’m not the only one who felt this pain.
What Is COMPASS Skills?
COMPASS stands for Personal Alignment Skills OS. It’s a collection of three SKILL.md files you drop into Claude Code or Codex. So think of them as adding a project manager to your agent’s brain — not engineering skills like “write tests” or “refactor this,” but meta-skills that keep your agent aligned and on track across sessions.
The package ships three skills, each targeting a distinct pain point in multi-session agent work:
| Skill | What It Does | When To Use It |
|---|---|---|
| task-clarifier | Prompts the agent to ask clarifying questions before starting ambiguous or high-cost work. Prevents wasted tokens on wrong assumptions. | Before any complex task where the goal isn’t crystal clear. |
| task-forest | Maintains a repo-local task DAG (directed acyclic graph) that persists across sessions. Shows relationships between tasks, what’s done, what’s blocked. | Multi-session projects with 6+ interdependent tasks. |
| user-profile-keeper | Stores your preferences permanently — communication style, risk tolerance, file conventions. The agent reads it automatically on startup. | Any project where you’re tired of telling the same tool the same preferences every session. |
But the genius here is that each skill works independently — you don’t need all three. If your main pain point is context loss across sessions, just install task-forest. If your agent keeps running off in the wrong direction, task-clarifier alone might be enough. But together, they create a lightweight project management layer that didn’t exist in the AI agent ecosystem before.
I Installed It — Here’s What Happened
Install was dead simple. One command:
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code
And it took about 30 seconds. But the trick is that COMPASS uses the existing skills CLI ecosystem (the same one that powers agent-skills), so if you’ve already got skills set up, this is literally a single line. And no config files, no PATH adjustments.
But here’s what surprised me most: the install doesn’t just drop files — it wires them into your agent’s startup sequence. The next time you open Claude Code in that repo, the skills are just there. $task-clarifier, $task-forest, and $user-profile-keeper become available as commands.
So I tested it on a project I’d been running across sessions — building a CLI tool that parses Docker Compose files into an SVG architecture diagram. The kind of thing where session 1 is “brainstorm the approach,” session 2 is “write the parser,” session 3 is “generate the SVG,” and by session 4 you’ve forgotten why you picked SVG over Mermaid in the first place.
So with $task-clarifier invoked before session 2, the agent paused and asked: “Should I assume a specific YAML structure or handle edge cases like multi-file compose projects?” And that’s exactly the kind of question I’d forget to mention until I’m 300 tokens deep into the wrong approach. Saved me a good 20 minutes of rework right there.
Then $task-forest showed me the DAG — which tasks depended on what, which were blocked, which were done. And it even exports an HTML visualization. Even for a CLI tool running in a terminal, that’s pretty slick. I could see at a glance that “SVG rendering” was blocked on “data model design” — something I’d been vaguely aware of but never had written down.
And $user-profile-keeper is one of those things you don’t realize you need until you have it — kind of like Claude Memory for your chat context, but focused on your personal preferences instead. I set my preferences once — “I prefer verbose output for exploration, terse for execution, and never touch the README without asking” — and the agent remembered them across every subsequent session. No more re-stating the same ground rules.
COMPASS vs The Skills Ecosystem
COMPASS doesn’t replace the other skills tools — it’s a different layer entirely. Here’s where it fits in the current space:
| Tool | Focus Area | Stars | COMPASS Differentiator |
|---|---|---|---|
| agent-skills | Engineering workflow (spec/plan/build/test/ship) | 52.5k | COMPASS handles alignment and project management, not code output |
| agnix | Agent config linting | 283 | COMPASS doesn’t lint — it structures task workflow across sessions |
| SkillSpector | Security scanning of SKILL.md files | 3.1k | COMPASS focuses on productivity, not vulnerability detection |
| COMPASS | Task alignment + DAG tracking + user profiling | 204★ | The only tool that cares about what you build, not just how you build it |
But this table is probably the clearest way to see why COMPASS matters: every other tool in the ecosystem is about process — how to write better code, how to write safer configs. Still, COMPASS is the first tool that asks “are we even building the right thing?” That’s a fundamentally different question, and it’s one that becomes critical as soon as your project spans more than one session.
What to Watch Out For
No tool is perfect, and COMPASS has real limitations I bumped into during testing:
Skills CLI dependency. If you’re on Cursor, Gemini CLI, or any agent that doesn’t support the SKILL.md ecosystem, COMPASS won’t work. It’s built specifically for Claude Code and Codex. The npx skills tool is growing, but it’s not universal yet.
204 stars is early days. Still, the project launched just 2 days ago. The API surface could change, and the community is tiny. I wouldn’t bet a production-critical workflow on it without a backup plan. The core concepts are solid, but expect rough edges.
task-forest is powerful but can feel heavy. For simple 2-3 task projects, maintaining a task DAG is overkill. You’ll get the most value on projects with 10+ interdependent tasks spanning multiple sessions. For single-session work, you probably won’t use it at all.
No multi-agent sharing. If you’re running a team of agents — or multiple Claude Code sessions on the same project — each agent gets its own task-forest. And there’s no shared project-wide view yet. The author is aware of this and it’s on the roadmap, but for now you’re working in isolation.
Documentation is sparse. The README covers installation and basic usage, but deeper patterns — like how to customize task-clarifier’s prompting style, or how task-forest handles task deletion — aren’t documented yet. Still, you’ll need to read the SKILL.md files themselves to understand the full capability.
Bottom Line
So COMPASS fills a real gap in the AI agent ecosystem. agent-skills taught agents how to code. agnix taught them to follow better configs. SkillSpector taught them security hygiene. COMPASS is the first to teach them what to code and why — turning your AI coding agent from a one-shot executor into something that can actually manage a long-running project.
For anyone running multi-session agent projects — CLI tool builders, multi-step refactors, or research that spans days — the three skills package is worth the 30-second install. Grab it, wire it in, and see if your next multi-session project feels less like herding cats.