COMPASS Skills: AI Agent State Management

COMPASS Skills addresses the critical need for persistent state management in long-running AI agent workflows. It provides a suite of four local skills—task clarification, task memory, conversation handoff, and user profiling—to maintain context across AI sessions. This empowers AI coding agents and their users by preventing state loss, reducing redundant work, and ensuring task alignment, thereby enhancing productivity for complex, multi-stage AI projects.

How It Works

COMPASS organizes AI agent state into four distinct, locally managed workflows packaged as SKILL.md components. The task-clarifier acts as a gatekeeper, aligning goals, scope, and acceptance criteria before executing ambiguous or high-risk tasks. task-forest maintains a repository-local Directed Acyclic Graph (DAG) tracking task dependencies, progress, and deviations. session-handoff-prompt compresses the current AI conversation's state into a concise prompt for seamless continuation in new sessions. Finally, user-profile-keeper stores auditable, correctable local preferences for communication and risk tolerance. This approach leverages local files and standard libraries, offering a robust, privacy-preserving state layer for AI agents.

Quick Start & Requirements

Installation is managed via the npx skills CLI. To list available skills, run npx skills add dongshuyan/compass-skills --list. For Claude Code, use npx skills add dongshuyan/compass-skills --skill '*' -a claude-code. For both Codex and Claude Code, use npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code. Manual installation involves copying the skills/ directory contents. The system relies on Node.js (for npx) and Python's standard library for its scripts. Compatibility is designed for agent runtimes supporting the SKILL.md format, including Claude Code, Codex, and OpenCode/OpenClaw.

Highlighted Details

• Local-First Data Management: All runtime data, including task progress and user profiles, is stored locally, ensuring privacy and preventing data exfiltration. Secrets are explicitly excluded from profiles.
• SKILL.md Ecosystem: Skills are packaged using the SKILL.md standard, promoting broad compatibility across various AI agent frameworks.
• Task Forest DAG Visualization: Provides a visual representation and structured management of complex task hierarchies and their interdependencies.
• Proactive Task Clarification: The task-clarifier skill enforces alignment and decision-making before initiating potentially costly or risky operations.

Maintenance & Community

The project has been shared openly on Linux.do. While specific community channels like Discord or Slack are not listed, the roadmap indicates plans for building reusable skills from task histories, upgrading existing skills based on feedback, and enhancing state summarization and task recommendation capabilities. No major contributors or sponsorships are highlighted.

Licensing & Compatibility

The project is released under the permissive MIT License, allowing for broad adoption and integration, including in commercial applications. It is designed for compatibility with agent environments that support the SKILL.md package format.

Limitations & Caveats

A significant security caveat exists for the user-profile-keeper: it stores profile data in local plaintext without encryption. Users are strongly cautioned against storing sensitive information such as passwords, private keys, or verification codes within this profile. The project appears to be under active development, with a roadmap outlining future enhancements.