COMPASS Skills
A local-first skills OS for AI agents that adds goal alignment, a task graph, pause/resume, cross-conversation handoff, and controlled skill self-evolution to long-running work.
Evidence shows strong least-privilege design: writes confined to user-approved directories, session-handoff-prompt read-only by default, upgrader plan-only; high-risk actions require explicit confirmation; SECURITY.md states data boundaries and a secrets exclusion list, candidly disclosing plaintext storage. Deductions: rollback is an asserted 'auditable, retractable' property with no concrete rollback mechanism shown; source attribution points only to an individual publisher and a Linux.do share, with unverified identity.
Included tests align closely with README claims (77 tests, schema validation, render checks), showing good self-consistency. Deductions: installation depends on the external npx skills CLI with behavior recorded only for 1.5.11/1.5.23; failure messages are visible in tests but not systematized into a uniform error spec.
Nine skills have clear purposes; a compatibility table covers Claude Code, Codex, OpenCode; invocation via explicit $skill-name; boundaries are explicit (e.g., pause-and-resume cannot recover a closed conversation). Deduction: Windows/Linux compatibility is enforced by contracts, not validated on physical hosts, as the author admits.
Directory layout, SKILL.md conventions, example prompts, install commands, MIT license, and known limitations (alpha status, plaintext storage, pending visual pass) are thorough. Deductions: no CHANGELOG or repository-level version history; single-maintainer project with no governance or response commitment; no FAQ, only examples.
The five-state framework (user/project/goal/pause/handoff) offers real marginal value; output shapes (task-forest HTML, handoff prompts, offline interview report) are directly usable; the Markdown + Python-stdlib approach keeps cost low and benefit clear. No execution evidence exists, but that is excluded from static scoring, so full marks stand.
Claim traceability is strong: tests assert at field level, validation status cites exact versions and commands; the interview report enforces source_status/source_locator to separate fact from inference. Deduction: external claims (Skill validator, byte-identical published files) cannot be independently corroborated in this static review and remain author assertions.
- user-profile-keeper uses local plaintext storage; never store passwords, tokens, private keys, or highly sensitive personal data in the profile.
- Windows/Linux compatibility is enforced by code contracts, not validated on physical hosts; pilot before cross-platform use.
- Publisher identity is unverified; review the SKILL.md files and scripts under skills/ yourself before installing.
- The run-history-skill-upgrader self-evolution loop relies on the 'explicit approval' convention; verify each upgrade plan's scope before approving it.
- No CHANGELOG or version history exists, making behavior changes hard to trace across upgrades; pin the installed version.
What does this agent do, and when should you use it?
COMPASS Skills (repo: dongshuyan/compass-skills, MIT, alpha) is a collection of nine SKILL.md skill packages that address context loss when AI work spans many turns or conversations. It ships five runtime collaboration skills (task-clarifier, task-forest, pause-and-resume, session-handoff-prompt, user-profile-keeper), two run-history skill-engineering skills (run-history-skill-builder, run-history-skill-upgrader), one academic-humanizer skill for de-AI-ifying scholarly prose, and one local hiring-support skill (assess-interview-candidate). All runtime data stays on the local workspace: no task or profile data is uploaded and no browser credentials are read. Skills are packaged as Markdown instructions with YAML frontmatter, installed via the skills CLI or by copying the skills/ folders, and work across agent runtimes including Claude Code and Codex. Helper scripts run locally using the Python standard library; assess-interview-candidate requires Python 3.10 or later.
After installation, skills are invoked explicitly in an AI conversation as $skill-name. task-clarifier gates ambiguous, costly, or externally visible work by identifying user-owned decisions and asking 1-3 focused questions with recommended answers before executing. task-forest maintains a repo-local task forest/DAG (usually under .agent-workbench/task-forest/) recording goals, subtasks, dependencies, progress, deviations, decisions, and conversation history, with HTML export and a live DAG view. pause-and-resume stops unfinished work at the nearest safe boundary, records a checkpoint inside the current conversation without creating files, and resumes from the recorded first action when the user says continue. session-handoff-prompt compresses the current conversation, workspace evidence, and task-forest exports into a paste-ready handoff prompt; it is read-only by default and can redact local paths and credential-like strings for shareable versions. user-profile-keeper maintains a local, auditable profile under .compass-skills/user-profiles/v1 or COMPASS_USER_PROFILE_HOME. run-history-skill-builder packages completed or repeatedly refined workflows into new skills; run-history-skill-upgrader synthesizes session evidence into an upgrade plan and edits files only after explicit approval. academic-humanizer removes AI-sounding patterns from academic prose while preserving claims, citations, and logic. assess-interview-candidate turns an authorized resume and job description into an audit layer plus an offline HTML report containing only a candidate overview, job-relevant uncertainties, and 12-18 interview questions.
- Developers running multi-day, multi-conversation work in Claude Code or Codex who need task-forest to preserve task structure and progress.
- Users handling interrupted long work within one AI conversation who want pause-and-resume to checkpoint at a safe boundary and resume later.
- Users moving in-progress work into a fresh AI conversation who need session-handoff-prompt to produce a paste-ready continuation prompt.
- Users who want scope, acceptance criteria, and risks aligned before executing vague or risky requests, via task-clarifier.
- Academic authors who want to remove AI-sounding wording from English or Chinese prose without changing claims or citations, via academic-humanizer.
- Recruiters who need a structured, auditable offline interview report from an authorized resume, via assess-interview-candidate.
What are this agent's strengths and limitations?
- Portable across runtimes: one SKILL.md package works in Claude Code, Codex, and other SKILL.md-compatible agents; pause-and-resume passes the Skill validator and installs byte-identically into Codex and Claude Code skill roots.
- Fully local data model: no uploads of task or profile data, no credential extraction, and run-history-skill-upgrader is plan-only by default, enabling a controlled self-evolution loop gated on explicit approval.
- Five runtime skills cover the full state chain of long agent work — clarification, task graph, pause/resume, cross-conversation handoff, and user profile — with explicit read/write boundaries (session-handoff-prompt is read-only toward task-forest).
- Transparent validation: the public install path is verified with [email protected] and 1.5.23, and assess-interview-candidate passes 77 unit and public-package tests on Python 3.11 and 3.14.
- The project is alpha, and this release was not run on physical Windows or Linux hosts; cross-platform behavior is enforced only through contracts.
- pause-and-resume requires the host to retain the same conversation, so it cannot recover a killed process, a closed conversation with unavailable history, or work moved to another conversation.
- user-profile-keeper uses local plaintext storage with no encryption; the README warns against storing passwords, tokens, private keys, or highly sensitive personal data.
- assess-interview-candidate's independent live-browser visual pass for the portrait layout is still pending, and its Python 3.10+ requirement is extra setup cost for users without code execution.
How do you install or deploy this agent?
Prerequisites: Node.js with npx available; assess-interview-candidate needs Python 3.10+. List skills first: npx skills add dongshuyan/compass-skills --list. Install all skills for Claude Code: npx skills add dongshuyan/compass-skills --skill '*' -a claude-code. Install for both Codex and Claude Code: npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code. Manual install: copy the nine folders under skills/ into the agent's local skills directory, keeping their references/, scripts/, assets/, evals/, and agents/ subdirectories intact. Note: the README does not state a specific minimum Node.js version for the skills CLI itself.
How do you use this agent?
After installation, invoke skills directly in an AI conversation with $task-clarifier, $task-forest, $pause-and-resume, $session-handoff-prompt, $user-profile-keeper, $run-history-skill-builder, $run-history-skill-upgrader, $academic-humanizer, or $assess-interview-candidate; hosts may also use native syntax such as $pause-and-resume in Codex or /pause-and-resume in Claude Code. Agents without native skill routing can follow AGENTS.md and read skills/pause-and-resume/SKILL.md directly. Example prompts in the README include asking session-handoff-prompt to "create a balanced continuation prompt for a new AI conversation" with goal and requirements, or instructing pause-and-resume to "pause this unfinished task at the nearest safe boundary" without creating a checkpoint file; on return, say continue in the same conversation. For multi-skill installs, use pause-and-resume when the same conversation remains available and session-handoff-prompt when moving to a fresh one.
How does this agent compare with similar options?
The README names no direct competitors; its differentiator versus single-purpose prompts or skills is that COMPASS is a nine-skill system including run-history-based skill building and controlled skill upgrading (run-history-skill-builder/upgrader), where most skill repos offer only point functionality.