Xskill Helper

xskill-helper

xskill is a thin client + background daemon that (1) mounts your team's shared Skills into every AI-agent tool you use (Claude Code, Codex, OpenCode, Cursor, Trae, DeepSeek Harness) and (2) collects your agent trajectories and syncs them to a team server; you choose which projects are uploaded (see "Controlling which trajectories are uploaded"). You join a server once, then it keeps skills in sync and auto-updates itself.

xskill init can install this guide into chosen harnesses on this machine. xskill connect also installs it after a team join. Invoke it as /xskill-helper from Claude Code, Codex, Cursor, and the other supported tools.

All state lives under ~/.xskill/:

Getting started

After pip install xskill, local trajectory search does not need a team server. The first xskill traj search checks for a connection. If there is no xskill connect and this machine has not been initialized, it scans detected harnesses, converts their sessions into ~/.xskill/*_sessions, and builds the local index. After that, xskill traj search and xskill traj read work on this computer.

For a guided setup that lists harnesses, turns on trajectory processing, and asks which agents should get this guide:

xskill init

xskill init -y is the non-interactive form: scan every detected harness and install /xskill-helper into all of them. --no-skill skips the guide. --skills-only only installs the guide. --force rescans even if the local index already exists.

Interactive xskill init then asks whether to join a team server. Enter, skip, or an empty address/token all leave the machine usable locally. Do not treat a skipped connect as failure. If they want to connect later, or run a standalone team server:

xskill connect <host:port> --token <token> --name <user-id>
xskill serve --server

Never send the user to a public hub or any address you were not given. If they do not have host, token, or name, show the connect command as the example and ask their server operator. The operator prints the token with xskill serve --server. Do not invent an address or token, and do not paste one from the internet.

After a successful handshake, connect installs this guide and starts the background daemon. Later reconnects can omit the address and token; they reuse ~/.xskill/team_client.json.

In the agent, invoke this guide as /xskill-helper.

Controlling which trajectories are uploaded

Rules live only on this machine. A mode decides what happens to projects without a rule; the server and this machine each have one, and the stricter wins (allowlist is stricter than denylist):

• allowlist — nothing is uploaded except projects you allow.
• denylist — everything is uploaded except projects you deny (server default).

A server set to allowlist requires it from every client on this version or newer; older clients do not know the field.

xskill privacy status                 # effective mode + every discovered project and its decision
xskill privacy mode allowlist         # this machine: only upload allowed projects (server cannot loosen it)
cd ~/code/my-service && xskill privacy allow   # allow this project (and subdirectories)
xskill privacy deny ~/code/secret     # never read or upload this project
xskill privacy clear ~/code/secret    # drop the rule, back to the mode default
xskill privacy review                 # interactive walk through discovered projects
xskill connect <host:port> --token <t> --privacy allowlist   # set the mode before the first upload

A skipped trajectory is never read, never uploaded and never marked as uploaded, so allowing it later uploads it on the next scan. A trajectory whose sidecar records no working directory (Cursor and Trae never do) cannot be matched to a project: it follows the mode default and status lists it separately. Rules never delete what was already uploaded.

Generate or rewrite a Skill

generate does not invent a Skill from scratch. It reads trajectories the team server already allows this client to see, and the instruction only describes what to create or change. The job may wait for a free SkillEdit seat; the CLI streams queue and run logs. When it finishes, the Skill is committed to main and pinned on the initiator's recommendation list.

xskill generate "创建一个排查 Python 内存泄漏的 Skill，包含常用诊断命令"
xskill generate "改写现有的 python-memory-debug Skill，补充 Windows 排查步骤"
xskill generate --name alice,bob "根据这些用户的成功案例生成数据库迁移 Skill"

--name is a comma-separated list of employee ids the agent should read first. Omit it and the agent may search every trajectory the server authorizes. If the CLI says the server is too old, ask the operator to upgrade the team server.

Import an existing Skill

import takes a local Skill folder (or a parent that contains several) into the team's own repo. This is not upload: import becomes a first-party Skill on main, while upload only lands in the user's SkillHub share.

xskill import ./my-skill
xskill import ./skills-parent --json