using-xskill
Use when installing, configuring, or operating xskill (the `xskill` CLI / `pip install xskill`) — starting the daemon, registering trajectory dirs, joining a team server, understanding how trajectories become Skills, or rebuilding/re-distilling the skill library after a model change.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 129
- Forks
- 27
01 前言 Front Matter
- name
- using-xskill
- description
- Use when installing, configuring, or operating xskill (the `xskill` CLI / `pip install xskill`) — starting the daemon, registering trajectory dirs, joining a team server, understanding how trajectories become Skills, or rebuilding/re-distilling the skill library after a model change.
02 资源文件 3
- 参考文档references/installation.md3.8 KB
- 参考文档references/mechanisms.md3.7 KB
- 参考文档references/rebuilding-skill-library.md5.0 KB
03 SKILL.md 正文
Using xskill
Overview
xskill distills reusable Skills (SKILL.md folders) out of the real execution
trajectories of coding agents (Claude Code, Codex, OpenCode, Cursor, …). A background
daemon watches each agent's session logs, slices them into single-intent atoms,
clusters atoms into skills, and writes/versions each skill in its own git folder. New
skill versions only replace old ones when real traffic shows they serve users better
(canary A/B by UX score) — not by an LLM grading itself.
Core mental model: raw trajectory → atoms → candidate routing → SKILL.md → canary A/B → installed into every agent's skill dir. You operate the daemon; the daemon does the distilling.
When to Use
- Installing xskill or filling in
~/.xskill/config.yaml(LLM + embedding endpoints) - Starting/keeping the daemon running (
xskill serve), or backfilling old trajectories - Joining or hosting a team server (
xskill serve --server/xskill connect) - Understanding the agent pipeline, atoms, canary/UX scoring, or deployment modes
- Re-distilling the whole skill library (e.g. after switching to a stronger model)
Quick Reference
| Command | What it does |
|---|---|
pip install xskill |
Install (Python 3.9+) |
xskill serve |
Standalone daemon: FastAPI + watcher; first run writes ~/.xskill/config.yaml then exits |
xskill serve --server |
Team server: owns all LLM calls + git; prints a join token |
xskill connect <host:port> --token <t> |
Join a team server as a thin client |
xskill registry add <path> |
Backfill / watch an extra trajectory directory |
xskill traj search <query> / xskill search <query> |
Search trajectories or skills |
xskill read <path> --eco <eco> |
Batch-ingest db trajectories (ngagent/opencode) |
xskill rebuild [--force] |
Re-distill from existing raw trajectories (see reference) |
xskill stats |
Token usage & estimated cost |
The daemon is the engine: most commands only change state in the DB; nothing is
distilled unless xskill serve (or the team server) is running.
Progressive Disclosure — read on demand
- Install & configure (config.yaml fields, per-agent collect/install paths, team
client setup):
references/installation.md - How it works (TaskAgent → TaskClusterAgent → SkillEditAgent, atoms, canary/UX
scoring, standalone vs team mode):
references/mechanisms.md - Rebuild the skill library (a ready-to-run prompt that walks a model through
re-distilling correctly):
references/rebuilding-skill-library.md
Common Mistakes
- Running
rebuildwith no daemon up.rebuildonly resets DB state; the watcher inservedoes the actual re-split/re-cluster every 30s. No daemon = nothing happens. - Deleting raw
~/.xskill/*_sessions/*.md. Those are the input to distillation — delete them and you can no longer rebuild. - Expecting DeepSeek to do embeddings. DeepSeek has no embedding endpoint; point the
embedding:block at DashScope / OpenAI / Ollama. - Putting tokens in public places. Team join tokens must never land in a public repo or chat log.
04 同仓库更多 Skills
demo-skill
A demo skill used to verify openclaw startup install path
xskill-demo-marker
A unique marker skill installed by xskill, used to verify openclaw sees it
xskill-helper
Use this skill for xskill. Trigger when the user wants to init, connect or join a team server, generate or rewrite a team Skill from trajectories, search download upload or import team Skills, look up this user or a teammate's past chats across Claude Code Codex Cursor OpenCode Trae DeepSeek Harness and ngagent, upgrade the client, or debug a stuck daemon. Team chats: xskill traj search then traj read. This machine only: add --local to read ~/.xskill/*_sessions. Invoke as /xskill-helper.
xskill-dev
Use when developing xskill itself — editing agent tool docstrings, changing the generate agent tool surface, or verifying what schema the Agno framework actually sends to the model. Covers the dump_schema workflow and where tool descriptions come from.
xskill-registry-db-first
XSkill 数据访问原则:文件系统是内容真相,由 worker 同步进库;面板与业务读 请求只走数据库;内核 agent loop 可直接写盘。适用于改 dashboard、recommend、 team、pipeline、ecosystems 等读路径,以及审查是否又引入业务侧扫盘。