5分钟上手COMPASS:一条命令安装并调用你的第一个AI技能(新手快速开始)
5分钟上手COMPASS:一条命令安装并调用你的第一个AI技能(新手快速开始)
COMPASS 是一个本地优先的个性化 AI 任务总控 Skills 系统(Personal Alignment Skills OS for AI Agents),它给 AI agent 装上需求澄清、任务跟踪、对话续接、用户画像等一套现成的本地 AI 技能。这篇新手教程带你在 5 分钟内完成一条命令安装 COMPASS,并调用你的第一个 AI 技能,全程不上传数据、无需注册账号。
🧭 先认识 30 秒:COMPASS 是什么
简单说,COMPASS 用 8 个本地技能回答 AI 协作中的 4 个核心问题:
- 知人:我是谁、偏好什么(
$user-profile-keeper本地用户画像) - 知向:我的需求到底是什么(
$task-clarifier需求对齐) - 知事:任务做到哪里、属于哪个大目标(
$task-forest任务森林) - 知续:换一个新 AI 对话怎么接着干(
$session-handoff-prompt续接 prompt)
以上为 COMPASS 的三步核心协作流:先沉淀用户画像,再对齐需求,最后把任务结构化成任务森林并导出可视化地图。所有数据都保存在你自己的电脑上。
⚡ 安装前准备:只需确认 1 个前提
COMPASS 以 SKILL.md 技能包形式分发,用 Python 标准库和 Markdown 运行,不依赖云服务。你只需要确认:
| 前提 | 说明 |
|---|---|
| Node.js | 安装命令通过 npx 执行,系统已安装 Node.js 即可 |
| 支持 SKILL.md 的 AI agent | Claude Code、Codex、OpenCode、OpenClaw 等均可;不支持的 agent 可按 AGENTS.md 轻量适配 |
没有其他了——不用账号、不用开网络服务、不用数据库。
🚀 一条命令安装:最快 COMPASS 技能安装步骤
第 1 步(可选):先看看有哪些技能可装
npx skills add dongshuyan/compass-skills --list
第 2 步:安装全部技能到你的 agent
给 Claude Code 安装全部技能:
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code
Codex 和 Claude Code 都装:
npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code
💡 小贴士:
--skill '*'表示全装;只想装部分技能时,把*换成具体技能名即可,多技能仓库按需安装更清爽。
不想用 npx?手动安装也只需 1 步:把 skills/ 目录下需要的技能文件夹复制到你 agent 的本地 skills 目录即可,注意保持 references/、scripts/、assets/ 等子目录完整,详细对照见 README.zh.md 的「安装和 Agent 兼容」一节。
💬 调用你的第一个 AI 技能:$task-clarifier 实战
安装完成后不需要任何配置,直接在 AI 对话里用 $ 前缀点名技能即可:
$task-clarifier 我要买个旅行箱,你告诉我一下哪个最好?
你会看到它不会立刻丢给你一堆产品链接,而是把模糊的"最好"拆成 1-3 个带推荐答案的关键问题(用途场景、预算范围、最看重什么),你只需回复选项字母;几轮下来,它会给出一段可确认的完整需求陈述。这就是"先对齐、再执行"的协作方式,适合任何需求模糊、成本高或有风险的任务。
以上为 task-clarifier 技能在真实终端中的运行效果:每个问题都附带选项和推荐答案,回答越简单,对齐越快。
8 个技能的调用入口一览:
$task-clarifier 需求澄清与风险门禁
$task-forest 任务森林 / DAG 进度总控
$session-handoff-prompt 生成新 AI 对话续接 prompt
$user-profile-keeper 本地协作画像(可审计、可撤回)
$run-history-skill-builder 把跑通的流程沉淀成新技能
$run-history-skill-upgrader 让已有技能受控自我进化
$academic-humanizer 去除学术论文中的 AI 语气
$assess-interview-candidate 生成结构化面试评估报告
各技能的完整说明和推荐 prompt 模板见 README.zh.md,例如 skills/task-clarifier/SKILL.md 定义了它的澄清循环与确认格式。
🗺️ 进阶玩法:用任务森林给长任务"装个仪表盘"
当任务开始变长,用 $task-forest 把对话中的目标、子任务、依赖、进度和决策维护成一张仓库内的任务图,它还能导出离线 HTML:树视图、DAG 视图、任务详情卡和推荐队列,让下一个 AI 对话接手时清楚"为什么做、做到哪、下一步做什么"。
上图左侧的"当前核心技能"就是你现在已装好的 8 个技能;右侧 roadmap 技能(本机代理控制室、任务调度器等)陆续开源中。
🔒 安全与隐私:你的数据留在本地
新手最关心的"安全吗",答案写得很直白:
- 不联网上传:任务数据、用户画像、对话续接内容全部保存在本地(
$task-forest默认存.agent-workbench/task-forest/,画像默认存.compass-skills/user-profiles/v1,可用COMPASS_USER_PROFILE_HOME改路径) - 不碰敏感凭证:不读取浏览器 cookie、token、credential
- 高风险动作(删除、覆盖、发布等)必须经你明确确认
- 唯一提醒:用户画像是本地明文存储,不要往里面存密码、token 等敏感信息
完整边界见 SECURITY.md,技能清单元数据在 skills.sh.json。
📌 接下来学什么
- 想动手写自己的第一个技能包:从 skill-writing-tutorial.html 教程开始
- 想看某个技能的规则细节:读对应目录下
skills/<技能名>/SKILL.md与references/ - 安装或调用遇到问题:优先在 AI 对话里让 agent 对照 README.zh.md 检查安装目录是否正确
装好、调通、跑通第一个 $task-clarifier,你就已经迈进了 AI 任务总控的世界——剩下的 7 个技能,用同样的 $ 前缀随时召唤。



