ChatCrystal Agent Skills

April 29, 2026 · View on GitHub

English | 简体中文

ChatCrystal 现在在 skills/ 下维护三个可追踪、可发布的 agent skills：

  • chatcrystal-task-recall
  • chatcrystal-debug-recall
  • chatcrystal-task-writeback

每个 skill 目录都是自包含的，目标是可以作为独立 skill asset 发布。

为什么是三个 Skills

这个拆分对应 ChatCrystal Core 当前的生产接口：

  • recall_for_task：通用任务召回
  • debug mode 下的 recall_for_task：面向故障排查的召回
  • write_task_memory：任务完成后的经验写回

这样能让每个 skill 保持窄范围、易触发、适合上架。我们有意不发布第四个 umbrella skill，因为它会重复已有行为，并且容易与三个聚焦工作流漂移。

从本仓库安装

开放 skills 生态支持从 Git 仓库安装 skill，也可以指定仓库里的单个 skill。

示例：

npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-recall
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-debug-recall
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-writeback

安装本仓库中的全部三个 skills：

npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-recall
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-debug-recall
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-writeback

Full Mode with ChatCrystal Core

Skills 单独也有价值，但完整 memory loop 需要 ChatCrystal Core 和 MCP。

手动配置路径：

  1. 安装 ChatCrystal Core：
npm install -g chatcrystal
  1. 启动本地 ChatCrystal server：
crystal serve -d
  1. 配置你的 Agent 暴露 ChatCrystal MCP server：
{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"]
    }
  }
}

ChatCrystal MCP 使用 stdio transport。Agent client 应通过 command 和 args 启动它，不要注册成 HTTP/SSE MCP URL。如果某个工具单独要求 ChatCrystal HTTP API endpoint，请使用 http://localhost:3721，不要使用裸 http://127.0.0.1。

Full mode 启用后，ChatCrystal MCP 暴露：

  • search_knowledge
  • get_note
  • list_notes
  • get_relations
  • recall_for_task
  • write_task_memory

Degraded Mode

如果 ChatCrystal Core 或 MCP 不可用：

  • recall skills 应继续工作，但不能声称已经召回记忆
  • writeback 只有在 write_task_memory 实际成功时才能声称已持久化
  • auto writeback 需要稳定 run key；没有 run key 时，应输出 memory candidate，而不是静默切换为 manual persistence

这些 skills 不会在自身工作流中自动运行 ChatCrystal 安装命令。

发布建议

当前推荐的 source of truth 是本仓库。初始发布不需要单独的 chatcrystal-skills 仓库，因为 skills 生态可以从多 skill GitHub 仓库中安装指定 skill。

本仓库发布规范：

  • 每个可发布 skill 都放在 skills/ 下的受版本管理子目录中
  • 每个 skill 保持自包含，包含 SKILL.md 和可选的 agents/ metadata
  • 避免依赖 .agents/ 或 docs/superpowers/ 这类被忽略的本地目录
  • 仓库内受版本管理的文档要与实际 MCP surface 保持一致

如果未来 skill 的发布节奏、贡献模型或品牌定位与 ChatCrystal Core 明显分离，再重新评估是否需要独立 skills 仓库。