Skip to content

agent-skills.md

Latest commit

 

History

History
106 lines (71 loc) · 3.69 KB

agent-skills.md

File metadata and controls

106 lines (71 loc) · 3.69 KB

ChatCrystal Agent Skills

English | 简体中文

ChatCrystal now ships three tracked, publishable agent skills under skills/:

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

Each skill folder is self-contained and intended to be publishable as a standalone skill asset.

Why Three Skills

The split matches the current production interfaces in ChatCrystal Core:

  • recall_for_task for general task recall
  • recall_for_task in debug mode for failure-oriented recall
  • write_task_memory for post-task memory writeback

This keeps each skill narrow, triggerable, and store-friendly. We intentionally do not ship a fourth umbrella skill because it would duplicate behavior and drift from the three focused workflows.

Install from This Repository

The open skills ecosystem installs skills from Git repositories and can target an individual skill in a repository.

Examples:

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

Install all three from this repository by running the three explicit commands:

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

The skills are useful on their own, but full memory-loop behavior requires ChatCrystal Core plus MCP.

Manual setup path:

  1. Install ChatCrystal Core:
npm install -g chatcrystal
  1. Start the local ChatCrystal server:
crystal serve -d
  1. Configure your agent to expose the ChatCrystal MCP server:
{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"]
    }
  }
}

ChatCrystal MCP uses stdio transport. Agent clients should launch it with command and args, not register it as an HTTP/SSE MCP URL. If a tool separately asks for the ChatCrystal HTTP API endpoint, use http://localhost:3721 rather than bare http://127.0.0.1.

With full mode enabled, ChatCrystal MCP exposes:

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

Degraded Mode

If ChatCrystal Core or MCP is unavailable:

  • recall skills continue without blocking and must not claim any memory was recalled
  • writeback must not claim persistence unless write_task_memory actually succeeds
  • auto writeback requires a stable run key; without one, the skill should emit a memory candidate instead of silently switching to manual persistence

The skills do not auto-run ChatCrystal installation commands as part of their workflow.

Publishing Guidance

The current recommended source of truth is this repository. A separate chatcrystal-skills repository is not required for initial release because the skills ecosystem can install named skills from a multi-skill GitHub repository.

Publishing guidelines for this repository:

  • keep each publishable skill in a tracked subdirectory under skills/
  • keep each skill self-contained with SKILL.md and optional agents/ metadata
  • avoid depending on ignored local-only directories such as .agents/ or docs/superpowers/
  • keep the tracked docs in this repository aligned with the actual MCP surface

Re-evaluate a dedicated skills repository later if the skill release cadence, contribution model, or branding diverges materially from ChatCrystal Core.