dongshuyan/compass-skills · v1.0 · MIT

COMPASS Skills · AI Agent 本地技能生态

用 SKILL.md 文件把 AI coding agent 的行为能力打包成分解可复用的技能单元——任务澄清、记忆管理、对话交接、用户画像，让 agent 在任意会话中快速获得团队级上下文感知。

330
Stars (6 天)
4
内置技能
SKILL.md
技能格式
npx
安装方式
task-clarifier
目标澄清技能
task-forest
任务 DAG 技能
session-handoff
对话交接技能
user-profile
用户画像技能

一句话定位

COMPASS Skills 是一个面向 AI coding agent 的本地技能（Skill）操作系统。它用 SKILL.md 文件格式定义技能元数据、使用触发词和执行逻辑，通过 npx skills add 安装到项目本地，让 Claude Code、Codex、OpenClaw 等 agent 运行时在任意对话中快速激活对应技能。

项目受 Matt Pocock 的 @skills CLI 启发，但将技能作用域从"全局安装的 npm 包"下沉到"项目本地的 .claude/skills/ 目录"，解决了跨项目上下文污染问题，并引入了 AI 辅助的技能审计工作流。

架构总览

COMPASS Skills 由三层构成：技能格式规范 → CLI 安装工具 → AI 审计工作流：

SKILL.md
技能描述格式
→
skill-inspector
AI 审计脚本
→
npx skills add
CLI 安装工具
→
.claude/skills/
项目本地存储

技能文件是核心契约——Agent 通过识别触发词激活技能，技能描述了"何时用、怎么用、什么情况下不用"。

SKILL.md 格式解析

每个技能是一个独立目录，含 SKILL.md 主文件和可选的 examples/ 目录。SKILL.md 的 frontmatter 遵循固定 schema：

skills/task-clarifier/SKILL.md (frontmatter)
---
name: task-clarifier                          // 技能唯一标识符
description: |-                          // 触发词 + 适用场景的完整描述
  Convergent need-alignment system. Before executing
  any non-trivial request, ask questions (1–3 per turn
  ...
triggers:                               // 激活关键词（空格分隔，OR 语义）
  ambiguous high-cost high-risk preference-sensitive
  best better which-one recommend help-me-choose
examples:                               // 可选：典型对话示例
  - when: "用户说'帮我优化这个系统'"
    response: "我需要先澄清几个问题：..."
---

Body 部分是技能的执行逻辑说明，用 Markdown 编写但格式自由。task-clarifier 的 body 描述了一个多轮澄清协议：

  • 每轮最多问 3 个问题，每个问题附带推荐答案选项
  • 覆盖维度：目标（outcome）、约束（constraints）、验收标准（acceptance criteria）、风险边界（risk boundaries）
  • 结束时必须确认共识（shared understanding），才进入执行阶段
设计亮点：触发词的多语言支持
task-clarifier 的触发词同时包含英文（best better which-one recommend）和中文（最好 推荐 哪个 你来决定），这意味着技能激活对使用中英混合对话的开发者同样有效。

四个内置技能深度解析

① task-clarifier — 目标对齐协议

task-clarifier 解决的是 agent 执行中最常见的失效模式：用户给了一个模糊指令，agent 直接动手，返工率极高。它的核心创新是"收敛性澄清"——每轮只问 1-3 个最关键的元问题，不做无限追问。

body 定义的执行流程：

01
检测激活词识别触发词，判断是否进入澄清模式
↓
02
收集维度从 outcome / constraints / acceptance criteria / risk 四维度构建问题列表
↓
03
分轮提问每轮最多 3 问，附推荐答案，引导用户快速收敛
↓
04
确认共识总结理解，请求确认后才进入执行

② task-forest — 任务 DAG 管理

task-forest 是最复杂的技能。它在项目本地维护一个任务森林（Task Forest）——即一个以目标为根、子任务为枝的 DAG 结构。每个节点记录：

  • goal：任务目标描述
  • subtasks：子任务列表及依赖关系
  • progress：进度（todo / in-progress / done / blocked / deferred）
  • deviations：执行过程中的偏差记录
  • decisions：做出的关键决策及其理由
  • conversation history：对话历史摘要

它支持导出任务图 HTML——这意味着可以在 CI/CD 流程中嵌入任务状态报告，或在 Code Review 时作为上下文摘要。

③ session-handoff-prompt — 对话交接协议

这是解决"长程任务换 session"问题的关键技能。当用户要求"handoff / restart / continuation / fresh-session resume"时，session-handoff-prompt 生成一个粘贴即用的交接提示，包含：

🎯
Goal Summary

当前会话的核心目标，精炼为 1-2 句话

📍
Progress Report

已完成的工作、当前状态、下一步计划

⚠️
Constraints

已知约束、风险边界、不应该做的事

📋
Next Steps

下一步具体动作，附执行顺序建议

④ user-profile-keeper — 用户协作画像

user-profile-keeper 在 .claude/user-profile.md 维护一个本地持久化用户画像，包含：

  • communication preferences：沟通风格（简洁 / 详细、中文 / 英文）
  • risk style：风险偏好（保守 / 激进、重构 vs. 小步迭代）
  • recurring working context：常驻工作上下文（使用的技术栈、常见项目结构）
  • capability boundaries：已知的能力边界（不擅长什么）
  • privacy boundaries：隐私边界（哪些信息不应进入记忆）

该画像在每次会话开始时由 agent 自动加载，而不是靠"人工在 system prompt 里写"。这解决了 system prompt 遗忘和跨会话偏好漂移问题。

skill-inspector：AI 辅助技能审计

COMPASS Skills 还包含一个 skill-inspector 工作流——用 AI 本身来审计技能文件的质量：

skill-inspector audit workflow
// 1. AI 阅读 SKILL.md 原文
// 2. AI 模拟目标用户在多种场景下的激活效果
// 3. AI 识别：
//   - 遗漏的触发词（false negative）
//   - 误激活的触发词（false positive）
//   - 模糊的执行描述（执行不确定性）
//   - 缺少示例的复杂决策点
// 4. AI 生成改进建议并更新 SKILL.md

安装与使用

terminal
# 列出所有可用技能
npx skills add dongshuyan/compass-skills --list

# 安装全部技能到 Claude Code
npx skills add dongshuyan/compass-skills --skill '*' -a claude-code

# 安装全部技能到 Claude Code + Codex
npx skills add dongshuyan/compass-skills --skill '*' -a codex -a claude-code

# 在 AI 对话中激活技能
# AI 通过触发词自动识别，或用户手动调用：
$task-clarifier   // 启动目标澄清
$task-forest      // 打开任务 DAG
$session-handoff  // 生成交接提示
$user-profile     // 查询/更新用户画像

与现有方案对比

维度COMPASS Skillsmattpocock/skillsOpenClaw Skills
技能存储位置项目本地 .claude/skills/全局 npm 安装Git 管理的 skills 目录
跨项目上下文污染无（项目隔离）有（全局生效）可选（可通过命名空间隔离）
技能激活方式触发词自动 + 手动 $invoke手动 /skill 命令显式函数调用
多 Agent 支持Claude Code + Codex主要 Claude全渠道
AI 辅助审计内置 skill-inspector无无
任务 DAGtask-forest（完整）无部分（memory-tree）
用户画像user-profile-keeper无memory-tree 部分覆盖

生态意义

COMPASS Skills 的核心创新不是某个具体技能，而是技能格式契约（SKILL.md）和本地优先的作用域隔离。它把"技能"从运行时能力变成了一个可版本化、可分享、可 AI 审计的文本资产。

这与 Matt Pocock 的 @skills CLI 一脉相承，但增加了：项目本地隔离、多 Agent 混用、AI 审计工作流。对于需要在多个项目中维护不同行为规范的团队，这套框架值得关注。