by dongshuyan
司南:个性化 AI 任务总控 Skills 系统 /COMPASS: Personal Alignment Skills OS for AI Agents
# Add to your Claude Code skills
git clone https://github.com/dongshuyan/compass-skillsGuides for using ai agents skills like compass-skills.
Last scanned: 6/17/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-06-17T09:02:12.368Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}compass-skills is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by dongshuyan. 司南:个性化 AI 任务总控 Skills 系统 /COMPASS: Personal Alignment Skills OS for AI Agents. It has 228 GitHub stars.
Yes. compass-skills passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/dongshuyan/compass-skills" and add it to your Claude Code skills directory (see the Installation section above).
compass-skills is primarily written in Python. It is open-source under dongshuyan on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh compass-skills against similar tools.
No comments yet. Be the first to share your thoughts!
Start here: Use & develop your own Skill ecosystem
A practical tutorial for using
SKILL.md, auditing reusable skills, drafting skills with AI, extracting real workflows, and building a local Skill ecosystem.
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code
COMPASS Skills gives AI coding agents three local skills: task clarification, repo-local task memory, and a local collaboration profile.
The project currently ships three SKILL.md skills:
| Skill | Purpose |
|---|---|
task-clarifier |
Aligns goals, scope, evidence, acceptance criteria, and risk boundaries before ambiguous, costly, or externally visible work. |
task-forest |
Maintains a repo-local task forest / DAG with goals, subtasks, dependencies, progress, deviations, todos, decisions, and session history. |
user-profile-keeper |
Maintains a local, auditable, correctable collaboration profile for communication preferences, risk style, and recurring working context. |
List the available skills before installing:
npx skills add dongshuyan/compass-skills --list
Install all skills for Claude Code:
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code
Install all skills for both Codex and Claude Code:
npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code
After installation, invoke the skills directly in a session:
$task-clarifier
$task-forest
$user-profile-keeper
For manual installation, copy the three folders under skills/ into the agent's local skills directory and keep their references/, scripts/, and agents/ subdirectories intact.
Long-running agent work needs three kinds of state:
COMPASS organizes that state into three local workflows:
task-clarifier is the entry point for ambiguous, high-cost, high-risk, evidence-sensitive, or externally visible work. It first identifies the user-owned decisions that must be made, asks 1-3 focused questions with recommended answers, confirms shared understanding, and only then searches or executes.
task-forest records long-running work structure: why a task exists, where it fits, how far it progressed, what changed, and what remains unresolved.
user-profile-keeper stores collaboration preferences locally. Future sessions use the profile to ask relevant questions and apply the right risk boundary. Current files, logs, and user-provided context remain the authority; secrets stay out of the profile.
user-profile-keeper -> who is the user and how should we collaborate?
task-forest -> where does this task fit and is it still aligned?
task-clarifier -> what should the agent do now?
Task forest HTML export:

Live DAG view:

Task detail view:

User profile and alignment flow:

Ecosystem map:
COMPASS works across agent runtimes as a SKILL.md package with Markdown instructions, YAML frontmatter, optional references/, optional scripts/, and optional agent metadata.
| Agent / environment | Recommended setup |
|---|---|
| Claude Code | Use npx skills add dongshuyan/compass-skills --skill '*' -a claude-code, or copy the folders under skills/ into Claude Code's custom skills directory. |
| Codex | Use the skills CLI with -a codex when supported by your environment, or use the repo as a local skills source. |
| OpenCode / OpenClaw / other agents | Keep AGENTS.md and load the matching SKILL.md first, then use references/ and scripts/ as needed. |
The scripts use Python standard-library components and run locally.
COMPASS keeps runtime data local:
task-forest stores task data under the current workspace, usually .agent-workbench/task-forest/.user-profile-keeper stores local profile data under .compass-skills/user-profiles/v1 by default, or a user-selected COMPASS_USER_PROFILE_HOME.Important: user-profile-keeper uses local plaintext storage without encryption. Do not store passwords, tokens, private keys, verification codes, or highly sensitive personal data in the profile.
See SECURITY.md for the security boundary.
Clarify a task before execution:
Use $task-clarifier to align the task below.
Task: ...
Material: ...
Constraints: ask user-owned decisions first; infer discoverable facts from files, context, or reliable sources. Ask only questions that change scope, method, evidence, format, safety, or acceptance criteria.
Output: ask 1-3 key questions with recommended answers first; once the core need is clear, restate your understanding in 2-5 lines and ask me to confirm.
Maintain the task forest for a workspace:
Use $task-forest to analyze the current session and maintain the task forest for this workspace.
Goal: create a task-forest proposal from long-running goals, tasks, progress, deviations, risks, decisions, and follow-ups in this session.
Requirements:
1. Read the current task-forest list and todo first; initialize task-forest if missing.
2. Identify which long-term goal this session served. If no relation is clear, ask me or create a question/risk node.
3. Save a proposal and show me the planned changes before applying.
4. After approval, apply, validate, export, and report the HTML path.
Initialize a local user profile:
Use $user-profile-keeper to initialize my local user profile.
Goal: build an auditable, correctable, retractable profile from a local questionnaire or the current context.
Boundaries:
1. Store locally only. Do not upload anything or read browser cookies, tokens, or credentials.
2. Do not save secrets, passwords, private keys, verification codes, or browser-session information.
3. Put inferred, private, sensitive, or conflicting claims into pending proposals for my review.
4. Report what was saved, proposed, skipped, or redacted.
The public install path has been validated with skills@1.5.11:
npx skills add dongshuyan/compass-skills --list finds all 3 skills.npx skills add dongshuyan/compass-skills --skill '*' -a claude-code --copy -y installs all 3 skills into a temporary project's .claude/skills/ directory.Planned additions:
task-forest as structured context.MIT. See LICENSE.
The project is developed publicly at dongshuyan/compass-skills.