---

Why xskill

“同事的coding agent已经做过的事情，你为什么不能直接拿来用？”

xskill is an enterprise-grade team skill evolution solution. It supports automatic skill distillation from trajectories, trajectory-profile-driven skill push, importing team skillhubs for recommendation, and skill evaluation.

• Automatic transfer of expert knowledge: One person's solution automatically reaches the entire team, so the shortest path is no longer wasted.
• Cross-Harness and cross-device shared evolution: Codex, Claude Code, and Cursor IDE all join the glorious evolution, together, in unison.
• Expert-modifiable skills: Think a skill is imperfect? Modify the local skill directly — changes are automatically learned by the cloud.
• Trajectories stay private: Sessions are desensitized before upload; keys, passwords, and related private data are never visible to others.
• Skills never rot: Skills are automatically evaluated, with user-actual-usage trajectory analysis producing evaluation scores and skill version score-trend line charts — a big-data microscope.

---

One person solves, all reuse

The moment someone on your team solves a problem in their own session, that solution becomes a skill — others' agents pick it up automatically. No one needs to write docs on purpose.

Across every agent and device — one shared skill library

Claude Code on the laptop, Codex on the server, Cursor in the IDE. xskill collects desensitized trajectories from all of them, evolves one shared skill library, and syncs results back to every agent you use.

Islands → collective evolution

Without a shared, self-improving skill library, every developer is stuck on an island, re-solving the same problems in isolation. xskill turns that wasted, siloed effort into shared experience that compounds.

---

Architecture

[!NOTE] The entire xskill pipeline is Agentic-Centric. First, trajectories are split into sub-trajectories (trajectory atoms) based on internal intent, then atoms are clustered and assigned to their corresponding skills. Once enough atoms accumulate, a skill edit is triggered, producing a new skill version. Different skill versions are tested on real user traffic, and the one with the higher user experience score wins and continues iterating as the main version. Every change is versioned and rollback-able. See docs/agent.md for details.

Accuracy

xskill is an unsupervised skill distillation solution that can evolve without building a dataset.

Current algorithm pipeline accuracy:

_{Setup: DeepSeek-V4-Flash · Claude Code · single mode
Pipeline: SkillOpt built-in evaluation pipeline · Official data split}

	Spreadsheet	ALFWorld	OfficeQA	Mean¹
XSkill	88.57	84.33	60.47	77.79
SkillOpt	87.86	77.61	51.16	72.21
Delta	+0.71	+6.72	+9.30	+5.58

_{¹ 表内数值为测试集通过率(%)，Mean 为三项基准的算术平均。Spreadsheet 与 ALFWorld 使用官方全量测试集，OfficeQA 使用官方划分的 1/4 子集。}

In the three evaluations completed so far, xskill outperforms SkillOpt in all of them, with an average lead of 5.58.

Evaluation Setup

To mimic a real team scenario, the eval env is namespace-isolated:

• 3 independent xskill-client instances
• 1 shared xskill-server
• Multiple LLM-simulated users responsible for QA interaction with the Agent

[!IMPORTANT] XSkill can keep evolving without explicit supervision signals. SkillOpt heavily depends on ValSet for the supervision signal its evolution requires. In Epoch 2, 3, and 4 of ALFWorld, ValSet all experienced accuracy overflow, causing evolution failure — an algorithmic flaw.

xskill supports switching the algorithm kernel; see "Optional: switch kernel" below.

---

🚀 Quick start

Solo mode (try it out)

If you only want trajectory search, no skill distillation:

pip install xskill          # Python 3.9+
xskill init                 # 扫描本机 agent，转换会话；不必填模型
xskill traj search 内存泄漏
xskill traj read <traj_id>  # 按行号读原文

If you have an LLM API and want more than trajectory search, you can start using skill distillation:

pip install xskill          # Python 3.9+
xskill serve                # 第一次启动只初始化配置文件 ~/.xskill/config.yaml

Open ~/.xskill/config.yaml and fill in two model endpoints (one LLM and one embedding vector model):

skill_dir: ~/.xskill/skill

llm:
  base_url: https://api.deepseek.com
  model:    deepseek-v4-flash
  api_key:  YOUR_KEY

embedding:
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
  model:    text-embedding-v4
  api_key:  YOUR_KEY
  dim:      0

The llm block above is the shared default model; keep existing config as-is.

If you want to use a different model or endpoint for the split, cluster, or edit stage of the pipeline, you can add an optional llm_agents section. It's fine to leave it out. For any stage or field that isn't specified, it will first check llm_skill, then fall back to llm. xskill generate still uses llm and llm_skill, and never reads llm_agents. After editing these sections, just restart xskill serve.

# 可选。不写这段的话，三个阶段都继续用上面的 llm
llm_agents:
  split:
    model: qwen-plus
  cluster:
    model: deepseek-v4-flash
  edit:
    base_url: http://localhost:8000/v1
    model: local-skill-editor
    api_key: local

Run xskill serve again — it will automatically detect every supported agent on your machine and start running, collecting agent trajectories and pushing skills to the corresponding harness.

[!NOTE] In solo mode you lose many deliberately designed features, so it's only recommended in the following situations.

1. You want to automatically chain your previous high-frequency workflows into skills
2. You have high-intensity Agent running requirements every day

Team mode (recommended)

The server admin configures config.yaml on the server and runs the centralized process:

xskill serve --server  # 会打印connect join命令，复制给组内同事便可。

Regular users run:

xskill connect <host:port> --token <token>  --name <工号/姓名>

By default everything is uploaded; to upload only some projects, run xskill privacy mode allowlist, then xskill privacy allow in each project directory, and check per-project decisions with xskill privacy status. On the server side, team.server.privacy_mode: allowlist can require all users to be on the allowlist (client must be this version or later).

After a successful connect, the guide gets installed into detected agents on your machine, including Claude Code, Codex, Cursor, and others. In the corresponding agent, type /xskill-helper to look up usages of generate, search, and upgrade. If you don't have a host and token, treat the command above as an example and ask your own server admin for the host, token, and employee ID. Do not connect to a public external instance.

Extra feature: admin panel

In config.yaml you can specify an admin identity:

dashboard:
  enabled: true
  public: true
  password: ""
  admins:
    - admin_name_1  # 管理员<工号/姓名>
    - admin_name_2
  admin_password: admin_passwd_123

Then enter the following on any PC:

xskill dashboard

which opens and logs into the admin panel (identity is auto-detected). Admins can:

• globally pin a skill
• pause trajectory upload for a user (e.g., anomalous behavior)
• globally take a skill offline and stop pushing it
• view skill version lineage and score trends

Regular users can:

• pin a favorite skill for themselves, preventing recommendation feed changes
• take an unwanted skill offline
• see which users their trajectories contributed to and who is using their skills
• view skill version lineage and score trends

Extra feature: instant skill generation or rewriting

generate does not create a skill from thin air: it extracts experience from trajectories already on the team server that you have access to; the natural-language instruction is only for describing what to generate or rewrite. After connecting to a team server that supports generate, you can create a skill like this:

xskill generate "创建一个排查 Python 内存泄漏的 Skill，包含常用诊断命令"

Same command also rewrites existing skills from trajectories; name the skill and goal in the instruction:

xskill generate "改写现有的 python-memory-debug Skill，补充 Windows 排查步骤"

Use --name to prefer specific users' histories; comma-separate multiple IDs. Omit to search all server-authorized trajectories:

xskill generate --name alice,bob "根据这些用户的成功案例生成数据库迁移 Skill"

The task may first wait for a free slot in the SkillEdit pool. The CLI continuously outputs queue and run logs; upon completion, the generated or rewritten skill is committed directly to the main branch and pinned to the initiator's recommendation list. If the CLI reports the server version is too old, contact your admin to upgrade the team server.

Extra feature: skill search and sharing

Beyond server-side auto-recommendation, clients can also search, download, and upload skills on demand:

xskill search <关键词>                                        # 搜索技能库，返回匹配技能与 ID
xskill download <skill-id>                                  # 交互式选择要安装的目标 agent
xskill download <skill-id> --agent claude-code --agent codex -y  # 命令行非交互式安装
xskill upload ./my-skill                                    # 将本地技能目录打包上传至团队共享库
xskill search <关键词> --download                            # 临时检索并下载至本地轮转槽位

Search combines keywords with semantic vectors for hybrid ranking by default; download persistently installs the specified skill to the corresponding agent; upload can publish a valid skill written by a team member to the team shared library with one click.

Extra feature: session & trajectory search

When stuck, search teammates' or local history sessions (trajectories) and distilled Atom tasks for proven contexts and troubleshooting commands:

xskill traj search "内存泄漏排查"                             # 检索历史会话轨迹
xskill traj search --name alice,bob "内存泄漏"                # 指定只检索特定成员的轨迹
xskill traj read <traj_id> --offset-start 1 --offset-end 100 # 按行号阅读会话原文

xskill atom search "OAuth token 刷新"                       # 检索已切分的原子任务片段
xskill atom read <atom_id>                                  # 查看该 Atom 对应的会话内容

When not connected to the team server, xskill traj search also supports searching local agents' historical sessions; you can also run xskill init for interactive scan and initialization. When connected to the team server, team search is initiated by default; add the --local flag to search locally only.

Extra feature: SkillHub support

Xskill supports importing skillhubs and including massive skills in recommendation and evaluation; the server admin just needs to configure ~/.xskill/config.yaml:

skillhub:
 enabled: true
 dir: /root/.xskill/skillhub_skills

Then place the internal corporate skillhub anywhere in that directory (multiple skillhubs supported), and xskill will automatically detect skills and include them in recommendation, pushing related skills to designated users automatically.

Optional: switch algorithmic kernel

xskill uses the built-in native kernel by default (three agents for splitting, categorizing, and editing) to drive skill evolution. In team mode, admins can switch kernel_id on the settings page to a third-party kernel (e.g., OpenEarth), letting an external algorithm take over the "generate skill after trajectories are ready" stage while the rest of the flow stays unchanged. Switching is optional; without a kernel section everything works as before.

See Algorithmic Kernel User Guide for steps and details.

---

🔌 Works with your agent

Agent	Status	Trajectory collection	Skill installation
Claude Code	✅ Verified	~/.claude/projects/	symlink → ~/.claude/skills/<name>/
Codex CLI	✅ Verified	~/.codex/sessions/ + ~/.codex/archived_sessions/	symlink → ~/.agents/skills/<name>/
OpenCode	✅ Verified	SQLite ~/.local/share/opencode/opencode.db	symlink → ~/.agents/skills/<name>/
OpenClaw	🟡 Implemented	~/.openclaw/agents/	copy → ~/.agents/skills/<name>/
Cursor	🟡 Implemented	~/.cursor/projects/*/agent-transcripts/	symlink → ~/.cursor/skills/<name>/
Trae	🟡 Implemented	IDE state.vscdb / CLI trajectory_*.json	symlink → ~/.trae-cn/skills/, ~/.trae/skills/
DeepSeek Harness (dsh)	🟡 Implemented	~/.dsh/sessions/ (both plaintext and default zstd sessions)	symlink → ~/.dsh/skills/<name>/
Any other agent	Manual	SDK xskill.adapters.submit_trajectory	copy/symlink SKILL.md directory

📖 Concepts

Term	Meaning
Trajectory	The complete record of one agent run session. Xskill maintains a large parsing ecosystem layer.
TrajectoryAtom	The smallest, single-intent slice of a trajectory, which serves as the raw material for skill generation.
Skill	A SKILL.md plus optional scripts, each versioned in its own git directory.
Canary	An A/B test of the current skill vs. the new candidate version on real traffic.
UX score	How well a particular skill served a user on a given atom, rated 1–10 from the interaction itself. Canary retains the version with the higher score.

---

🗺 Roadmap

• Dynamic concurrency: adjust concurrency dynamically based on internal vllm load to gain higher throughput
• Multi-tenancy: one instance serving multiple teams/departments
• Industrial-grade recommendation engine: finer-grained profiles and recommendation algorithms
• More agent adapters: Goose, OpenHands, Aider
• Trajectory lake: manage massive trajectories, server-side security alerts, Time-Travel feature

📰 Changelog

• 2026-08-27 v0.7.0: Generate trajectory reading switched to traj_search, traj_cards, atom_search, read_traj; wiki can log progress incrementally; xskill init can skip the connection step, and re-running it on an already-connected account will not disconnect it.
• 2026-08-17 v0.6.32a1: The pipeline now splits first and groups first on new trajectories; the dashboard can hot-edit seats and quota ratios without restarting agent-worker; a running generate waiting on the LLM gets hard priority; imported skills that have met trigger conditions get priority for editing seats.
• 2026-08-14 v0.6.31: xskill rebuild --force no longer aborts mid-way because .git/objects is non-empty; a full rebuild preserves skills brought in via xskill import, clearing only distilled artifacts.
• 2026-08-14 v0.6.30: After a team xskill import, the skill is pinned into the initiator's recommendation list; in the skill library, logged-in users can click the empty star to pin a skill into their own feed, with "pushed to me" and "pinned" status markers; imported skills appear in the skill library listing immediately.
• 2026-08-14 v0.6.30a3: xskill generate now prints status in a timely way in the CLI while queued or running, instead of waiting silently; even when the old install ledger contains regressed sequence numbers, import still works and reinstalls back into the harness.
• 2026-08-14 v0.6.30a2: Fixed an issue where, in team xskill generate, the agent forgot already-executed work after context compression.
• 2026-08-14 v0.6.30a1: Team mode gains xskill generate to write skills to the mainline per instruction; new xskill import to bring existing skills in.
• 2026-08-07 v0.6.29: Fixed a recommendation backfill issue.
• 2026-08-03 v0.6.29a6: Milvus is now an optional VDB; DashBoard supports selecting how many skills to push; Dashboard supports querying user grayscale status for Skill.
• 2026-08-03 v0.6.29a5: Introduced Milvus Lite vector index.
• 2026-07-30 v0.6.29a4: Dashboard gains a "My" page that regular users land on by default; contribution destinations and world messages support paginated browsing; supports reclaiming orphaned skills produced by client-side recommendation changes.
• 2026-07-30 v0.6.29a3: Recommendation engine optimized.
• 2026-07-20 —— v0.6.25: SkillHub now supports non-UTF-8 SKILL.md; Dashboard supports pausing/resuming trajectory ingestion for specified users.
• 2026-07-07 —— v0.6.2a2: Fixed Windows connect so the background daemon no longer requires admin privileges; the persistent process on Windows is iterated to usable.
• 2026-07-07 —— v0.6.2: Introduced user profiles and a skill recommendation engine; supports connecting to the service with a real-name employee ID; supports importing third-party skillhubs into the retrieval pool; added a background daemon for Windows (xskill start/stop/status) with CLI process management.
• 2026-05-29 —— Added Trae IDE / Trae Agent support.
• 2026-05-23 —— v0.5.0: Introduced team mode (client-server); introduced trajectory de-identification to protect privacy; supports Python 3.9; removed the git dependency.
• 2026-05-20 —— MIT open-sourced; published on PyPI: pip install xskill.
• 2026-05-12 —— Supports Claude Code, Codex, OpenCode; connected with OpenClaw and Cursor.

---

🙏 Acknowledgements

HKU OpenSpace, Alibaba Trace2Skill, ECNU AutoSkill, Microsoft SkillOpt

🤝 Contributing

Issues and PRs are welcome.

📝 Citation

@misc{xskill2026,
  title        = {xskill: Team-Level Skill Distillation, Sharing, and Evolution for Coding Agents},
  author       = {SkillNerds},
  year         = {2026},
  howpublished = {\url{https://github.com/SkillNerds/xskill}}
}

📄 License

MIT © 370025263. See LICENSE.