메뉴
Skill 创作质量标准 - Done When 完成判据、主动上下文发现、检查点设计规范。确保 Skills 具备自检能力，从"我猜我做完了"变成"我能确认我做完了"。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | skill-authoring-quality |
| description | Skill 创作质量标准 - Done When 完成判据、主动上下文发现、检查点设计规范。确保 Skills 具备自检能力，从"我猜我做完了"变成"我能确认我做完了"。 |
| version | 1.0.0 |
| tags | ["meta","skill-authoring","done-when","context-discovery","quality"] |
| author | Hermes |
| created | "2026-05-03T00:00:00.000Z" |
从"我猜我做完了"变成"我能确认我做完了"
这是 Agent 具备自愈、自迭代能力的前提。
| 支柱 | 说明 | 示例 |
|---|---|---|
| Goal | 任务目标 | 获取股票数据并验证 |
| Context | 上下文来源 | MemPalace + fact_store + 缓存 |
| Constraints | 约束条件 | 时间锚定、数据源优先级、缓存策略 |
| Done When | 完成判据 | 必检项（最关键杠杆） |
## ✅ Done When 完成判据
### 四大支柱
| 支柱 | 说明 | 本 Skill 对应 |
|------|------|--------------|
| **Goal** | 任务目标 | 【具体目标】 |
| **Context** | 上下文来源 | 【数据源】 |
| **Constraints** | 约束条件 | 【限制规则】 |
| **Done When** | 完成判据 | 下方必检项 |
### 必检项（全部满足才算完成）
#### 【任务：XXX】
- [ ] **检查项名称**
- 子项 1
- 子项 2
- **验证方法**：具体代码或命令
### 可选项（加分项）
- [ ] **优化项名称**
- 说明
- **验证方法**：具体代码或命令
### 失败处理
| 失败场景 | 处理路径 | 用户提示 |
|---------|---------|---------|
| 场景 1 | 处理方式 | 提示信息 |
### 自检代码示例
```python
def verify_done_when(task_type, ...):
"""验证 Done When 是否满足"""
# 具体验证逻辑
return True
#### 必检项设计原则
1. **可验证性**：每个检查项都有明确的验证方法（代码/命令）
2. **完整性**：覆盖任务的关键步骤，缺一不可
3. **客观性**：避免模糊表述，使用明确的标准
4. **可执行性**：Agent 能自动执行验证
#### 失败处理设计原则
1. **场景明确**：列举常见失败场景
2. **路径清晰**：给出明确的恢复路径
3. **用户友好**：提示信息清晰，不暴露技术细节
---
### 二、主动上下文发现机制
#### 三层架构
第一层：触发词扫描（instant，<10ms） ├─ 关键词匹配（股票代码、技术术语、项目名） └─ 正则表达式（金额、日期、时间）
第二层：语义检索（fast，100-300ms） ├─ MemPalace 语义搜索 ├─ fact_store 实体推理 └─ session_search 历史对话
第三层：关联发现（medium，<500ms） ├─ Tunnel 追踪（MemPalace 知识图谱） └─ 跨会话模式识别
#### 触发词设计原则
1. **精确性**：避免误触发（优先正则，其次关键词）
2. **优先级**：high/medium/low 分级，高优先级优先处理
3. **可扩展**：支持动态添加新触发词
4. **性能优先**：响应延迟 <500ms
#### 配置文件格式
```yaml
triggers:
- pattern: '\d{6}\.(SH|SZ)'
type: regex
actions:
- mempalace_search
- fact_store_probe
- skill_load: stock-data-acquisition
priority: high
description: "A股股票代码"
tool_name + args，而非直接调用Done When 设计：
效果：
Done When 设计：
效果：
| 指标 | 目标 | 测量方法 |
|---|---|---|
| 错误率降低 | ≥50% | 对比实施前后错误报告 |
| 自检覆盖率 | ≥80% | 必检项数 / 总检查点数 |
| 验证可执行性 | 100% | 每个必检项都有验证代码 |
| 指标 | 目标 | 测量方法 |
|---|---|---|
| Token 节省 | ≥30% | 对比实施前后 Token 消耗 |
| 准确率 | ≥95% | 上下文发现结果相关性 |
| 错误率 | ≤5% | 错误触发次数 / 总触发次数 |
| 响应延迟 | <500ms | 统计平均延迟 |
模糊表述 ❌
无法验证 ❌
过多必检项 ❌
过度触发 ❌
延迟过高 ❌
工具调用冲突 ❌
每个 Skill 的 description 必须包含：
description: |
[做什么] 简洁描述功能。
[什么时候触发] Use when: keyword1, keyword2, "user says X".
[什么时候别触发] Do NOT use for: related-but-different tasks.
检查点：
# GitHub 类
Do NOT use for:
- Committing without reviewing changes
- Force pushing to protected branches
- Deleting remote branches without backup
# Finance 类
Do NOT use for:
- Real trading without user confirmation
- Accessing sensitive financial data without authorization
- Executing trades in production environment
# Creative 类
Do NOT use for:
- Academic papers or research (preserve formal tone)
- Technical documentation that requires precision
- Legal or medical content (specialized language required)
## Known Gotchas
### [分类名称]
- **[具体问题]**: [问题描述]
```bash
[解决方案代码]
### 示例（github-repo-management）
```markdown
## Known Gotchas
### Authentication Issues
- **`gh auth status` fails silently**: Check if `GITHUB_TOKEN` environment variable is set
```bash
echo $GITHUB_TOKEN # Should show token, not empty
git remote -v && git branch -vv # Check remote and tracking
---
## 📊 Token 经济标准
| 指标 | 合格 | 优秀 | 说明 |
|------|------|------|------|
| SKILL.md 行数 | ≤500 | ≤300 | 避免过度加载 |
| Description 长度 | <1024 | <800 | 精炼触发信号 |
| 引用图深度 | ≤2 跳 | 1 跳 | 扁平化结构 |
---
## 🚨 常见错误
### ❌ 错误 1: Description 过于简单
```yaml
# 错误
description: Helps with documents.
# 正确
description: |
Generate technical documentation from code.
Use when: "write docs", "document API", "add comments", 生成文档.
Do NOT use for: blog posts, marketing copy, creative writing.
# 错误
description: AI image generation tool.
# 正确
description: |
AI image generation with reference images and batch processing.
Use when: "generate image", "画图", "text-to-image".
Do NOT use for:
- Video generation (use video-gen skill)
- Image editing (use image-editor skill)
- 3D rendering (use 3d-render skill)
# 错误
MUST use constructor injection. NEVER use field injection.
# 正确
Use constructor injection. Field injection breaks testability because we
cannot mock the field without Spring context.
docs/claude-skill-patterns-14.md - 14 个 Claude Skill 编写模式（完整学习笔记）SKILLS_OPTIMIZATION_PLAN.md - 系统化优化计划scripts/skill_optimizer.py - 批量优化工具适用范围：所有 Skill 创作和质量优化任务
维护原则：每次发现新的质量提升方法，更新本 Skill
将编码任务委派给 Claude Code（Anthropic 的 CLI 代理）。用于构建功能、重构、PR 审查和迭代编码。需要安装 claude CLI。 Use when: claude code, 编码任务, coding task, 代码审查, code review, 重构, refactoring, PR审查, Claude CLI. Do NOT use for: - Hermes 配置问题（用 hermes-agent skill） - Codex/OpenCode 任务（用 codex/opencode skills） - 非编码任务（用相应 skills） - 批量文件操作（用 file/terminal 工具）
Configure, extend, or contribute to Hermes Agent.
Hermes Fork 仓库完整维护指南 - 保守式更新 + 文档本地化 + 更新日志自动化 + GitHub 推送配置。涵盖：本地修改保护、冲突解决、性能优化合并、README 翻译、更新日志自动记录、Fork 推送全流程。
灵魂注入器 - 已合并到统一时间感知模块。 【v3.0 更新】时间感知功能已合并到 unified_time_awareness.py，避免重复注入。 原功能保留： - 搜索上下文注入（search.md） - 对话状态感知 移除功能（已合并）： - 时间感知 → unified_time_awareness.py
全局约束管理系统 - 时间感知、情境感知、对话状态感知的统一约束层。 在所有任务执行前自动注入约束条件，确保 AI 的行为符合人类期望。 Use when: 全局约束, constraints, 时间感知, time awareness, 情境感知, context awareness, 执行规范, Hook注入. Do NOT use for: - 具体任务执行（用其他执行类 skills） - 数据获取（用 stock-data-acquisition） - 股票分析（用 stock-analysis-framework） - 错误恢复（用 supervisor-mode） 触发场景： - 所有任务执行前的自动检查（通过 Shell Hook 注入） - 用户主动询问约束规则 - 发现执行偏离时的人工干预 核心约束类别： 1. 时间感知约束：深夜/周末/节假日行为规范 2. 情境感知约束：用户状态识别与响应策略 3. 对话状态约束：跨会话连贯性与话题衔接 4. 执行规范约束：Skill 执行合规性检查
分层分级记忆系统 - 六层记忆架构（L1-L6）+ 缓存优化。 L1 会话记忆 → L2 短期记忆 → L3 长期记忆 → L4 技能记忆 → L5 任务上下文 → L6 全息记忆。 Use when: 记忆系统, memory system, 六层记忆, L1-L6, 记忆分层, 上下文管理, 缓存优化. Do NOT use for: - 单次会话记录（用 L1 session） - Skill 创建（用 skill_manage） - 数据持久化（用 file_write） - 知识图谱（用 fact_store） v1.10.0 新增： - ✅ 缓存优化系统集成（DeepSeek Prefix Caching） - ✅ 平均缓存命中率 92%+，节省成本 80%+ - ✅ CLI 工具 hermes-cache（统计监控、优化建议） - ✅ 固定前缀策略（从 HERMES.md 读取核心约束） - 🎯 效果：Token 成本 -81%、延迟 -80%、缓存命中 92%+ v1.9.0 新增： - ✅ 六层记忆架构（L1-L6） - ✅ L2 精简方法论（2491→1021 chars，-59%） - ✅ 跨层协同优化（L2↔L5、L3↔L6、L4→L3） - ✅ l5_to_l2_injector.py（高频实体反向注入） - 🎯 效果：跨层一致性 +100%、重复录入 -80%