1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | compass-skills |
| 项目自述名称 | COMPASS Skills（中文：司南） |
| 作者/维护者 | Shuyan（个人开发者，清华大学） |
| 来源链接 | https://github.com/dongshuyan/compass-skills |
| 许可证 | MIT（数据来自 GitHub API，仓库内 LICENSE 文件确认） |
| GitHub Stars | 644（数据来自 GitHub API） |
| Forks | 54（数据来自 GitHub API） |
| 最新版本 | v0.3.0（仓库 tag；另有未打新标签的后续提交，最后一次提交时间 2026-07-11） |
| 安装方式 | 一条 npx skills add 命令，或手动复制 skills/ 下的技能文件夹 |
2. 功能介绍与亮点
compass-skills（COMPASS）是围绕“长程 Agent 协作状态”设计的本地优先 skills 系统，共 7 个 SKILL.md：
task-clarifier：高成本/对外可见任务开始前，先提炼 1-3 个关键问题并给推荐答案，确认后才让 Agent 动手task-forest：在工作区维护任务 DAG（目标/子任务/依赖/进度/决策历史），可导出离线 HTML 图谱session-handoff-prompt：把当前对话的目标、进展与下一步压缩成可直接粘贴到新对话的交接提示user-profile-keeper：本地保存沟通偏好、风险边界等协作画像，供后续会话复用run-history-skill-builder/-upgrader：把验证过的工作流打包成新技能，或把运行证据整理成升级方案（仅出方案，人工批准后才落地）academic-humanizer：中英文学术写作去 AI 味，同时保护论点、证据强度与引用不被改写
亮点：SECURITY.md、PUBLICATION_AUDIT.md 逐技能列出本地数据边界与发布前脱敏记录；关键技能均“只读/只出方案，人工确认才执行”；作者对 Issue 响应快，一次 Windows 锁清理问题数日内修复并给出对应 commit。
3. 适用场景
所属分类：元技能与 Agent 增强。适合长期用 AI 编程助手处理多次会话、需要任务在对话间保持连续性和上下文的开发者与知识工作者，也适合想把成熟工作流沉淀成可复用技能包的用户；academic-humanizer 额外覆盖中英文论文修改需求。
4. 跨 Agent 兼容性
- Claude Code：原生支持——README 给出专属安装命令
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code - Codex：支持——
skillsCLI 配-a codex参数即可，README 措辞为“当所在环境支持时”，非无条件保证 - OpenClaw：需适配——README 点名 OpenClaw，做法是保留
AGENTS.md通用协议，先读取对应SKILL.md再按需用references/、scripts/，非一键安装 - Hermes Agent：未验证——公开文档未点名；Issue 中有独立用户反馈在 OpenCode + oh-my-openagent 组合下实际用过，侧面印证
SKILL.md格式本身具备跨运行时可移植性
5. 推荐理由
长任务一断会话就得从头解释背景，个人偏好也留不下来。COMPASS 把“用户是谁”“任务进展到哪”“下一段对话该带什么上下文”拆成可审计的本地技能，配合前置澄清网关，让长程协作有地方存状态、也有地方对齐目标。安全边界写得清楚——不联网、不外传、改动前要过人工确认——对已在用多个技能、想要一个不越权记忆层的用户是低风险的起点。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | GitHub 644 stars、54 forks；两名与作者无关联的独立用户在 Issues 中报告过真实使用场景（其中一人明确说明在 OpenCode + oh-my-openagent 组合下长程运行），问题均在数日内被修复，显示真实采用而非单纯围观 |
| 可用性 | 9 | 一条 npx 命令即可为 Claude Code / Codex 安装；每个技能都配 references/、部分配 evals/，另有中英双语 README 与独立教程站；最近一次提交在 2026-07-11，维护活跃；无需任何付费依赖 |
| 安全性 | 8 | 见下方检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① shell 命令与权限范围 | 各技能仅调用自身目录下的本地 Python 标准库脚本（如 task_forest.py、profile_store.py），SECURITY.md 逐项列出每个脚本可写的本地路径 |
| ② 运行时联网外发 | SECURITY.md 明确声明技能本身不上传、推送、发布或远程写入任何内容；无外联目标 |
| ③ API key/凭据 | 日常使用不需凭据；SECURITY.md 明令禁止在本地画像中保存密钥、密码、令牌等敏感信息 |
| ④ 可疑指令 | 抽查 task-forest、academic-humanizer 的 SKILL.md 未见隐蔽指令或混淆代码；仓库附带 PUBLICATION_AUDIT.md 记录发布前对内部路径与私有示例的清理过程 |
| ⑤ 作者信誉 | 个人开发者，GitHub 账号 2016 年注册、171 个公开仓库，未见刷 star 或营销话术痕迹 |
| ⑥ License | MIT，仓库根目录 LICENSE 文件确认 |
| ⑦ 最近维护 | 最后一次提交 2026-07-11，活跃维护 |
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| yao-meta-skill（yaojingang） | 把重复工作流转成结构化 skill，附带评测、多目标编译与发布前审查看板 | 侧重“从经验产出新 skill 并跑通发布治理”；compass-skills 核心是任务/会话状态的连续性管理，技能打包只是附属功能之一 |
| one-skill-to-rule-them-all（rebelytics） | 纯提示词的后台观察者，静默记录工作模式与修正，定期汇总成技能改进建议 | 面向“技能库自己怎么变好”，不落地任务图谱或会话交接产物；compass-skills 面向单次长任务内部的上下文连续性，两者解决不同阶段的问题 |
8. 用户评价
- Ronifue（GitHub Issues #2）：在 OpenCode + oh-my-openagent 组合下长程运行时，报告了 Windows 环境下
task-forest锁文件清理失败会打断流程的具体复现步骤；作者随后重构锁恢复逻辑并给出对应 commit - YeungHoiChiu（GitHub Issues #4）：建议调整目录层级以便被第三方技能管理工具识别，作者确认功能已支持，仅需将分支名对齐为
master
9. 其他补充
提供中文（README.zh.md）与英文双语文档，另有独立教程页面；仓库保留 PUBLICATION_AUDIT.md，记录每次发布前对内部路径、私有示例的脱敏过程。
10. 安装使用方式
为 Claude Code 安装全部技能：
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code同时为 Codex 安装：
npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code仅查看可用技能列表：
npx skills add dongshuyan/compass-skills --list手动安装：将 skills/ 目录下对应技能文件夹整体复制进所在 Agent 的本地技能目录，并保留 references/、scripts/、evals/、agents/ 子目录结构。安装后按 $task-clarifier、$task-forest 等名称直接在对话中调用即可，无需重启。OpenClaw 等无原生技能支持的 Agent，需先加载仓库根目录的 AGENTS.md 获取调用协议。
11. 注意事项
user-profile-keeper的本地画像默认明文存储、不加密，官方文档提示不要写入密码、密钥等高敏信息- 仓库标注状态为 “alpha”，
task-forest并发锁机制此前在 Windows 下出现过需手动清理的问题，虽已修复，长时间无人值守流程仍建议留意 - 目前只有一名核心维护者，长期可持续性需自行评估
- Codex、OpenClaw 的支持均非“零配置”，建议正式依赖前先做小范围验证