sensei

Sensei

“真正的大师不是靠讲授，而是靠打磨来教导。”

使用 Ralph 循环模式 自动优化技能的 frontmatter——迭代改进技能，直到其合规性达到中高水平且测试通过。

帮助

当用户说“sensei help”或询问如何使用 sensei 时：

╔══════════════════════════════════════════════════════════════════╗
║  SENSEI - Skill Frontmatter Compliance Improver                  ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  USAGE:                                                          ║
║    Run sensei on <skill-name>              # Single skill        ║
║    Run sensei on <skill-name> --fast       # Skip tests          ║
║    Run sensei on <skill1>, <skill2>        # Multiple skills     ║
║    Run sensei on all Low-adherence skills  # Batch by score      ║
║    Run sensei on all skills                # All skills          ║
║                                                                  ║
║  WHAT IT DOES:                                                   ║
║    1. READ    - Load skill's SKILL.md and count tokens           ║
║    2. SCORE   - Check compliance (Low/Medium/Medium-High/High)   ║
║    3. SCAFFOLD- Create tests from template if missing            ║
║    4. IMPROVE - Add WHEN: triggers (cross-model optimized)       ║
║    5. TEST    - Run tests, fix if needed                         ║
║    6. TOKENS  - Check token budget                               ║
║    7. SUMMARY - Show before/after comparison                     ║
║    8. PROMPT  - Ask: Commit, Create Issue, or Skip?              ║
║    9. REPEAT  - Until Medium-High score achieved                 ║
║                                                                  ║
║  TARGET SCORE: Medium-High                                       ║
║    ✓ Description > 150 chars, ≤ 60 words                         ║
║    ✓ Has "WHEN:" trigger phrases (preferred)                     ║
║    ✓ No "DO NOT USE FOR:" (risky in multi-skill envs)             ║
║    ✓ Has "INVOKES:" for tool relationships (optional)            ║
║    ✓ SKILL.md < 500 tokens (soft limit)                          ║
║                                                                  ║
║  MCP INTEGRATION (when INVOKES present):                         ║
║    ✓ Has "MCP Tools Used" table                                  ║
║    ✓ Has Prerequisites section                                   ║
║    ✓ Has CLI fallback pattern                                    ║
║    ✓ No skill-tool name collision                                ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

配置

Sensei 使用以下默认值（可在提示词中指定以覆盖）：

设置	默认值	描述
技能目录	skills/ 或 .github/skills/	存放 SKILL.md 文件的位置
测试目录	tests/	存放测试文件的位置
Token 软限制	500	SKILL.md 的目标值
Token 硬限制	5000	SKILL.md 的最大值
目标分数	中高	最低合规水平
最大迭代次数	5	每项技能的循环上限

按以下顺序检查并自动检测技能目录：

1. 项目根目录中的 skills/
2. .github/skills/
3. 用户指定的路径

调用模式

单项技能

Run sensei on my-skill-name

多项技能

Run sensei on skill-a, skill-b, skill-c

按遵循度等级

Run sensei on all Low-adherence skills
Run sensei on all Medium-adherence skills

所有技能

Run sensei on all skills

快速模式（跳过测试）

Run sensei on my-skill --fast

GEPA 模式（深度优化）

Run sensei on my-skill --gepa
Run sensei on my-skill --gepa --fast
Run sensei on all skills --gepa

使用 --gepa 时，步骤 5（改进）将替换为 GEPA 进化优化。 GEPA 不使用基于模板的改进，而是将现有测试框架用作适应度 函数，并使用大模型自动提出和评估多个候选改进方案。

GEPA 仅评分模式（不调用大模型，只评估当前质量）：

Run sensei score my-skill
Run sensei score all skills

Ralph 循环

对每项技能执行此循环，直到分数 >= 中高：

步骤 1：读取

加载技能的当前状态：

{skills-dir}/{skill-name}/SKILL.md
{tests-dir}/{skill-name}/ (if exists)

运行 Token 计数：

npm run tokens -- count {skills-dir}/{skill-name}/SKILL.md

步骤 2：评分

检查 frontmatter，评估其合规性：

• 描述长度（>= 150 个字符，≤ 60 个单词；若目标仓库的 .sensei.json 或 AGENTS.md 偏好简短触发短语，则不受长度下限限制）
• “WHEN:”触发短语（优先）或“USE FOR:”
• 路由清晰度（“INVOKES:”、“FOR SINGLE OPERATIONS:”）
• 不包含“DO NOT USE FOR:”反向触发条件（在多技能环境中存在风险）

详细标准请参阅 references/scoring.md。

步骤 3：检查

如果分数 >= 中高且测试通过 → 转到摘要步骤。

步骤 4：搭建脚手架（如有需要）

如果 {tests-dir}/{skill-name}/ 不存在，则使用 references/test-templates/ 中的模板创建测试脚手架。在声称任何工具文件缺失之前，请使用 ls 或 git ls-files 验证——不要仅凭文件名作出判断。

步骤 5：改进 FRONTMATTER

优化 SKILL.md 描述，使其包含：

1. 以动作动词开头 - 首句：独特的动作动词 + 领域
2. 触发短语 - 使用“WHEN:”（优先）或“USE FOR:”，并包含 3-5 个有辨识度的引号短语
3. 描述保持在 60 个单词和 1024 个字符以内

⚠️ “DO NOT USE FOR:”存在依上下文而异的风险。 在多技能环境中（10 项以上技能且领域重叠），反向触发条款会引入恰恰导致错误技能被激活的关键词；在 Claude Sonnet 和快速模式匹配模型中尤其如此（证据）。对于规模较小、相互隔离的技能集（1-5 项技能），风险较低。如有疑问，请使用 WHEN: 和有辨识度的引号短语进行正向路由。

模板（跨模型优化）：

---
name: skill-name
description: "[ACTION VERB] [UNIQUE_DOMAIN]. [One clarifying sentence]. WHEN: \"[phrase1]\", \"[phrase2]\", \"[phrase3]\", \"[phrase4]\", \"[phrase5]\"."
---

模板（包含适用于高分的路由清晰度）：

---
name: skill-name
description: "**WORKFLOW SKILL** — [ACTION VERB] [UNIQUE_DOMAIN]. [Clarifying sentence]. WHEN: \"[phrase1]\", \"[phrase2]\", \"[phrase3]\". INVOKES: [tools/MCP servers used]. FOR SINGLE OPERATIONS: [when to bypass this skill]."
---

步骤 5-GEPA：使用 GEPA 改进（设置 --gepa 标志时）

替代步骤 5，采用自动化进化优化。步骤 6（改进测试）仍会正常运行。

1. 自动发现测试框架：读取 {tests-dir}/{skill-name}/triggers.test.ts，并自动提取 shouldTriggerPrompts 和 shouldNotTriggerPrompts 数组。

2. 构建评估器：构建一个 GEPA 评估器，对候选内容按以下标准评分：

   • 内容质量（包含 ## Triggers、## Rules、## Steps、USE FOR、WHEN）
   • Frontmatter 描述合规性（长度、触发短语）
   • 触发准确性（从描述中提取的关键词是否与测试提示词正确匹配）

3. 运行优化：调用 GEPA 自动评估脚本：

   python scripts/src/gepa/auto_evaluator.py optimize \
     --skill {skill-name} \
     --skills-dir {skills-dir} \
     --tests-dir {tests-dir} \
     --iterations 80
   

4. 检查输出：GEPA 会生成优化后的 SKILL.md 正文。向用户展示差异。 GEPA 评估器会根据现有测试自动生成，无需手动配置。

关键点：GEPA 将现有测试用作适应度函数，不会替代或修改测试。 大模型会提出改进后的 SKILL.md 文本，评估器则根据 CI 已使用的相同测试提示词对每个候选内容评分。只有得分更高的改进才会保留。

步骤 6：改进测试

更新测试提示词，使其与新的 frontmatter 匹配：

• shouldTriggerPrompts：至少 5 条提示词，与“WHEN:”或“USE FOR:”短语匹配
• shouldNotTriggerPrompts：至少 5 条提示词，涉及无关主题和不同技能的场景

步骤 7：验证

运行测试（设置 --fast 标志时跳过）：

# Framework-specific command based on project
npm test -- --testPathPattern={skill-name}  # Jest
pytest tests/{skill-name}/                   # pytest
waza run tests/{skill-name}/trigger_tests.yaml  # Waza

步骤 8：令牌

检查令牌预算：

npm run tokens -- check {skills-dir}/{skill-name}/SKILL.md

预算指南：

• SKILL.md：< 500 个令牌（建议值），< 5000 个令牌（硬性上限）
• references/*.md：每个文件 < 1000 个令牌

步骤 8b：MCP 集成（存在 INVOKES 时）

当描述中包含 INVOKES: 时，检查：

1. MCP 工具使用表：技能正文中是否包含该表？
2. Prerequisites 部分：是否记录了所需条件？
3. CLI 回退方案：MCP 不可用时是否有回退方案？
4. 名称冲突：技能名称是否与 MCP 工具名称匹配？

如果检查未通过，请参照 mcp-integration.md 中的模式添加缺失部分。

步骤 9：摘要

显示前后对比：

╔══════════════════════════════════════════════════════════════════╗
║  SENSEI SUMMARY: {skill-name}                                    ║
╠══════════════════════════════════════════════════════════════════╣
║  BEFORE                          AFTER                           ║
║  ──────                          ─────                           ║
║  Score: Low                      Score: Medium-High              ║
║  Tokens: 142                     Tokens: 385                     ║
║  Triggers: 0                     Triggers: 5                     ║
║  Anti-triggers: 0                Anti-triggers: 3                ║
╚══════════════════════════════════════════════════════════════════╝

步骤 10：询问用户

询问用户如何继续：

• [C] 提交 - 使用提交消息 sensei: improve {skill-name} frontmatter 保存
• [I] 创建 Issue - 创建包含摘要和建议的 Issue
• [S] 跳过 - 丢弃更改，转到下一个技能

步骤 11：重复或退出

• 如果评分低于中高，且迭代次数 < 5 → 转到步骤 2
• 如果迭代次数 >= 5 → 超时，显示摘要，然后转到下一个技能

评分速查

评分	要求
无效	描述 > 1024 个字符（超过规范硬性上限）
低	描述 < 150 个字符，或没有触发条件
中	描述 >= 150 个字符，且有触发条件，但 > 60 个词
中高	包含“WHEN:”（优先）或“USE FOR:”，且 ≤ 60 个词
高	中高 + 路由清晰（INVOKES/FOR SINGLE OPERATIONS）

⚠️ 在多技能环境（10 个以上存在重叠的技能）中，“DO NOT USE FOR:”风险较高——会导致快速模式匹配模型出现关键词污染。对于小型、隔离的技能集合则安全。为确保跨模型兼容，请使用带有 WHEN: 的正向路由。

MCP 集成评分（存在 INVOKES 时）

检查项	状态
MCP 工具使用表	✓/✗
Prerequisites 部分	✓/✗
CLI 回退模式	✓/✗
无名称冲突	✓/✗

完整评分标准请参阅 references/scoring.md。 MCP 模式请参阅 references/mcp-integration.md。

Frontmatter 模式

技能分类前缀

添加前缀以明确技能类型：

• **WORKFLOW SKILL** - 多步骤编排
• **UTILITY SKILL** - 单一用途的辅助工具
• **ANALYSIS SKILL** - 只读分析/报告

路由清晰度（高分标准）

当技能与 MCP 工具或其他技能交互时，请添加：

• INVOKES: - 此技能调用哪些工具/技能
• FOR SINGLE OPERATIONS: - 哪些情况下应绕过此技能

快速示例

之前（低分）：

description: 'Process PDF files'

之后（高分，含路由，针对跨模型进行优化）：

description: "**WORKFLOW SKILL** — Extract, rotate, merge, and split PDF files. WHEN: \"extract PDF text\", \"rotate PDF pages\", \"merge PDFs\", \"split PDF\". INVOKES: pdf-tools MCP for extraction, file-system for I/O. FOR SINGLE OPERATIONS: Use pdf-tools MCP directly for simple extractions."

更多转换前后示例，请参阅 references/examples.md。

提交消息

sensei: improve {skill-name} frontmatter

参考文档

• scoring.md - 详细的评分标准和算法
• mcp-integration.md - MCP 工具集成模式
• loop.md - Ralph 循环工作流详情
• examples.md - 转换前后示例
• configuration.md - 项目设置模式
• test-templates/ - 测试脚手架模板
• test-templates/waza.md - Waza 触发器测试格式

内置脚本

运行 npm run tokens help 查看完整用法。

Token 命令

npm run tokens count              # Count all markdown files
npm run tokens check              # Check against token limits
npm run tokens suggest            # Get optimization suggestions
npm run tokens compare            # Compare with git history

GEPA 命令

需要：pip install gepa（或 uv pip install gepa）。请参阅依赖要求。

# Score a single skill (no LLM calls, instant)
python scripts/src/gepa/auto_evaluator.py score --skill azure-deploy --skills-dir skills --tests-dir tests

# Score all skills
python scripts/src/gepa/auto_evaluator.py score-all --skills-dir skills --tests-dir tests

# Optimize a skill (requires LLM API — uses GitHub Models via gh auth token)
python scripts/src/gepa/auto_evaluator.py optimize --skill azure-deploy --skills-dir skills --tests-dir tests

# JSON output (for CI pipelines)
python scripts/src/gepa/auto_evaluator.py score-all --skills-dir skills --tests-dir tests --json

配置

创建 .token-limits.json 以自定义限制：

{
  "defaults": { "SKILL.md": 500, "references/**/*.md": 1000 },
  "overrides": { "README.md": 3000 }
}