AI Agent Engineer

AI Agent Engineer

编写一个 Workspace Skill

4 min read

编写一个 Workspace Skill

实践目标

在隔离 workspace 中创建一个只读 Session 检查 Skill，观察 summary、按需加载和 Tool 使用，不修改 nanobot 源码。

前置知识

  • 已读 新增 Skill；
  • 实验 workspace 中已有至少一个 Session；
  • rg 在 PATH 中可用；若不可用，删去 requirements 中的 rg。

需要阅读的代码

  • nanobot/agent/skills.py::SkillsLoader
  • nanobot/agent/context.py::build_system_prompt
  • nanobot/skills/weather/SKILL.md
  • tests/agent/test_skills_loader.py
  • tests/command/test_skill_command.py

先写下预测

  • 新 Skill 会不会完整进入每次 system prompt？
  • folder name 与 frontmatter name 不一致时，加载用哪个？
  • requirements 不满足时 /skill 会怎样显示？
  • Skill 是否能让 Agent 获得此前没有的文件权限？

实践步骤

1. 建立目录

在实验 workspace 中创建：

skills/
└── session-auditor/
    └── SKILL.md

内容：

---
name: session-auditor
description: Read-only inspection of nanobot Session JSONL files for learning and debugging.
metadata:
  nanobot:
    requires:
      bins:
        - rg
      env: []
---
 
# Session Auditor
 
## Use when
 
Use this skill when the user asks to inspect how one nanobot Session was persisted.
 
## Procedure
 
1. Confirm the workspace and session key.
2. List session files; do not guess the filename.
3. Read only the metadata line and the final four message records.
4. Never print credentials, full system prompts, or unrelated sessions.
5. Report roles, timestamps, tool-call relationships, and relevant metadata.
6. Separate confirmed facts from unknowns.
 
## Safety boundaries
 
- Do not edit, delete, rename, or repair Session files.
- Stop if the target Session is ambiguous.
- Redact secrets and unnecessary personal content.
 
## Verification
 
End with the exact file inspected and the number of records read.

2. 检查发现

使用同一 config/workspace 运行：

nanobot agent `
  --config "$nanobotLab\config.json" `
  --workspace "$nanobotLab\workspace" `
  --message "/skill"

预期列表出现 session-auditor。

3. 观察 system prompt

在 ContextBuilder.build_system_prompt() 断点查看：

  • always_skills 不包含它；
  • skills summary 含名称、description 和路径；
  • 完整正文尚未直接拼入。

4. 触发 Skill

nanobot agent `
  --config "$nanobotLab\config.json" `
  --workspace "$nanobotLab\workspace" `
  --session "learning:skill" `
  --message "请使用 session-auditor 检查 learning:tool-call，只报告角色顺序和工具调用关系。"

观察 Agent 是否：

  • 先读取 Skill；
  • 再列出/读取 Session；
  • 遵守只读和最小披露；
  • 报告实际文件与记录数。

预期观察

  • 普通 Skill 先以 summary 出现在 prompt；
  • 模型决定是否读取完整 SKILL.md；
  • Skill 约束工作流，但真正的文件访问仍由 read_file/list_dir Tool 执行；
  • workspace Skill 与 builtin loader 使用同一入口；
  • 行为可能受模型决策影响，loader 事实应由测试确定。

完成条件

  • /skill 能发现它；
  • context summary 正确；
  • Agent 至少一次读取完整 Skill；
  • 检查过程没有修改 Session；
  • 报告满足 Skill 的 Verification；
  • git status 显示 code-EN 无变化。

验证方法

运行 loader tests：

Set-Location "example\nanobot\code-EN"
python -m pytest tests\agent\test_skills_loader.py -q
python -m pytest tests\command\test_skill_command.py -q

再做一个负例：临时把 requirements 改成不存在的命令，确认 availability 变化；随后改回。

复盘问题

  1. 为什么正文不默认全部进入 system prompt？
  2. Skill 不被模型读取时，是发现失败还是决策问题？如何区分？
  3. 为什么只写“不要泄密”还不够？
  4. 什么时候应把这个 Skill 设为 always？本例是否适合？

下一篇：实现一个只读 Tool 插件

Backlinks