Skill
using-xskill
Use when installing, configuring, or operating xskill (the `xskill` CLI / `pip install xskill`) — starting the daemon,…
@skillnerdsInstall SkillAgent Memory
Skill
/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.
Install
$ npx -y skills add SkillNerds/xskill --skill xskill-dev --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/xskill-dev
Context preview
The summary Claude sees to decide when to auto-load this skill.
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.
SKILL.md
xskill-dev.SKILL.mdname: xskill-dev
description: 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.
Developing xskill
工具描述从哪来
Agno 框架直接把 `@tool` 装饰的 Python 函数 docstring 当作发给模型的工具描述， 参数说明也从 docstring 里解析。也就是说 docstring 就是模型上下文的一部分：
- 写给模型看，不写内部实现细节（内部细节放代码注释）。
- 系统提示词里不要再抄一遍工具清单，框架会自动注入 schema，抄了会漂移。
- generate 代理的轨迹工具在 `src/xskill/agents/traj_tools.py`，
通用工具在 `src/xskill/agents/agent_tools.py`， wiki 工具在 `src/xskill/agents/llm_wiki.py`。
改完 docstring 必跑：dump_schema
改任何工具的 docstring 或签名之后，跑一次导出脚本，看 Agno 实际生成的 schema 是什么样，确认模型看到的和你想的一致：
/home/admin/xskill/.venv/bin/python \
scratch/standalone-generate/tool_surface/dump_schema.py
输出写在同目录 `SCHEMA.txt`。对照检查：
- 每个工具的 description 是否完整、有没有被截断或混进实现细节；
- 参数名、类型、必填项是否与函数签名一致；
- 新增或删除工具后，工具总数是否符合预期（generate 面当前是 16 个）。
`SCHEMA.txt` 可以进 code review diff，reviewer 能直接看到模型侧的变化。
上下文预算的流式陷阱
`_wrap_with_context_mgmt` 只包 `model.invoke`。任何用 `stream=True` 跑 agent 的路径都会走 `invoke_stream`，完全绕过 compact、spill 和超长兜底，模型跑在 后端原生窗口里（DeepSeek 是 1M），而且日志里一条 CONTEXT 事件都不会有。 产品 GenerateAgent 用非流式 `agent.run()` 所以没事；写实验脚本、demo、 新 agent 入口时必须非流式，或先给 `invoke_stream` 补包装。判断预算机制 是否真在跑，看 agent.log 里有没有 CONTEXT 事件（Compacted context、 Spilled、Compact was not needed 任意一种）。
llm_cfg 里开剪裁的键名是 `enable_spill`，不是 `spill`。
相关材料
- 工具面设计与取舍：`docs/plans/2026-08-27-generate-tool-surface.md`
- 独立实验台（Phoenix 观测、变体对比）：`scratch/standalone-generate/`，
入口 `run_experiment.py`，`product` 变体加载产品 traj_tools 与产品 SYSTEM_PROMPT，是验证产品行为的首选变体。
Read more
name: xskill-dev description: 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.
Developing xskill
工具描述从哪来
Agno 框架直接把 `@tool` 装饰的 Python 函数 docstring 当作发给模型的工具描述， 参数说明也从 docstring 里解析。也就是说 docstring 就是模型上下文的一部分：
- 写给模型看，不写内部实现细节（内部细节放代码注释）。
- 系统提示词里不要再抄一遍工具清单，框架会自动注入 schema，抄了会漂移。
- generate 代理的轨迹工具在 `src/xskill/agents/traj_tools.py`，
通用工具在 `src/xskill/agents/agent_tools.py`， wiki 工具在 `src/xskill/agents/llm_wiki.py`。
改完 docstring 必跑：dump_schema
改任何工具的 docstring 或签名之后，跑一次导出脚本，看 Agno 实际生成的 schema 是什么样，确认模型看到的和你想的一致：
/home/admin/xskill/.venv/bin/python \ scratch/standalone-generate/tool_surface/dump_schema.py
输出写在同目录 `SCHEMA.txt`。对照检查：
- 每个工具的 description 是否完整、有没有被截断或混进实现细节；
- 参数名、类型、必填项是否与函数签名一致；
- 新增或删除工具后，工具总数是否符合预期（generate 面当前是 16 个）。
`SCHEMA.txt` 可以进 code review diff，reviewer 能直接看到模型侧的变化。
上下文预算的流式陷阱
`_wrap_with_context_mgmt` 只包 `model.invoke`。任何用 `stream=True` 跑 agent 的路径都会走 `invoke_stream`，完全绕过 compact、spill 和超长兜底，模型跑在 后端原生窗口里（DeepSeek 是 1M），而且日志里一条 CONTEXT 事件都不会有。 产品 GenerateAgent 用非流式 `agent.run()` 所以没事；写实验脚本、demo、 新 agent 入口时必须非流式，或先给 `invoke_stream` 补包装。判断预算机制 是否真在跑，看 agent.log 里有没有 CONTEXT 事件（Compacted context、 Spilled、Compact was not needed 任意一种）。
llm_cfg 里开剪裁的键名是 `enable_spill`，不是 `spill`。
相关材料
- 工具面设计与取舍：`docs/plans/2026-08-27-generate-tool-surface.md`
- 独立实验台（Phoenix 观测、变体对比）：`scratch/standalone-generate/`，
入口 `run_experiment.py`，`product` 变体加载产品 traj_tools 与产品 SYSTEM_PROMPT，是验证产品行为的首选变体。
Other skills on xskill.
@skillnerdsInstall Skill