技能优化
- 作者仓库星标 209
- 作者仓库 ai-coding-project-boilerplate
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @shinpr · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Skill Content Optimization
## Core Philosophy
1. **Evidence-Based**: Grounded in prompt engineering research, applied to skill authoring
2. **Concrete**: Each pattern provides detection criteria and transform methods
3. **Structure-Focused**: Optimizes expression and organization; domain knowledge remains unchanged
## Content Optimization Patterns
### P1: Critical (Must Fix)
Issues that directly reduce LLM execution accuracy when consuming the skill.
#### BP-001: Negative Instructions → Positive Form
| Detection | Transform |
|-----------|-----------|
| "don't", "do not", "never", "avoid" in skill instructions | Reframe as positive directive with equivalent constraint. **Exception**: Negative form is permitted only when ALL 4 conditions are met: (1) violation destroys state in a single step, (2) caller or subsequent steps cannot normally recover, (3) the constraint is operational/procedural, not a quality policy or role boundary, (4) positive rewording would expand or blur the target scope. If any condition is not met, rewrite in positive form. |
**Exception boundary examples**:
- Permitted: "Do not modify the command", "Do not add flags", "Do not execute destructive operations"
- Rewrite in positive form: "Do not invent issues" → "Base every issue on BP patterns or 9 principles", "Do not skip P1 issues" → "Evaluate all P1 issues in every review mode", "Do not give grade A when P1 exists" → "Assign grade A only when P1 count is zero"
Quality policies, role boundaries, scoring criteria, and general work rules always use positive form. Outputs that the caller validates, overwrites, or discards are never irreversible.
**Skill example:**
- Before: "Don't use generic variable names"
- After: "Use descriptive variable names that reflect purpose (e.g., `userId` not `x`)"
**Why critical for skills**: LLM attention mechanisms focus on negated content. Skill instructions with "don't" increase probability of the forbidden behavior.
#### BP-002: Vague Instructions → Specific Criteria
| Detection | Transform |
|-----------|-----------|
| "appropriate", "good", "proper", "best", "should be clear" | Replace with measurable if-then criteria or concrete thresholds. **Skill exception**: Expressions that the LLM can resolve unambiguously from input context (e.g., "where the user left gaps" when the user's prompt is available for comparison) are not vague — they describe a deterministic operation, not a subjective judgment. |
| Missing output format, scope, or success criteria | Add explicit constraints |
**Skill example:**
- Before: "Handle errors appropriately"
- After: "Error handling criteria: 1. try-catch for external API calls, file I/O, JSON.parse 2. Log: error.name, error.stack, timestamp 3. Re-throw with context if caller needs to handle"
**Why critical for skills**: Accounts for ~40% of execution variance. Every vague instruction forces LLM to guess.
#### BP-003: Missing Output Format → Structured Output
| Detection | Transform |
|-----------|-----------|
| Skill describes what to do but not the expected deliverable format | Add output section with structure, fields, and example |
**Skill example:**
- Before: "Analyze the code for issues"
- After: "Output format: `## Issues Found` with table: | Severity | Location | Description | Suggested Fix |"
**Why critical for skills**: Structured output constraints reduce hallucination and make skill results consistent.
### P2: High Impact (Should Fix)
Issues that reduce skill effectiveness when addressed.
#### BP-004: Unstructured Content → Organized Format
| Detection | Transform |
|-----------|-----------|
| Wall of text without headings | Apply standard section order (see below) |
| Multiple topics mixed in one section | Split into distinct headed sections |
| No tables for reference data | Convert lists of criteria/patterns to tables |
**Standard skill section order:**
1. Context/Prerequisites
2. Core concepts (definitions, patterns)
3. Process/Methodology (step-by-step)
4. Output format/Examples
5. Quality checklist
6. References
**Conditional**: Skip restructuring if skill is under 30 lines and covers a single topic.
#### BP-005: Missing Context → Explicit Prerequisites
| Detection | Transform |
|-----------|-----------|
| Skill assumes knowledge not stated | Add Prerequisites section listing required context |
| Domain terms used without definition | Add definitions inline or in a glossary table. **Skill exception**: Terms within the LLM's baseline knowledge (widely-used technical terminology, standard domain vocabulary) require no definition. Only project-specific terms, internal naming conventions, or domain jargon outside common LLM training data need explicit definition. |
| No "when to use" guidance | Add trigger conditions with concrete scenarios |
**Skill example:**
- Before: "Apply the strangler pattern for migration"
- After: "**Prerequisite**: Existing monolith with identifiable module boundaries. **When to use**: Replacing legacy module while maintaining production traffic."
#### BP-006: Complex Content → Decomposed Steps
| Detection | Transform |
|-----------|-----------|
| 3+ objectives in one instruction | Break into numbered steps with checkpoints |
| Sequential dependencies not explicit | Add dependency markers between steps |
| No intermediate verification | Insert checkpoint after each step |
**Conditional**: Skip decomposition for simple reference tables or single-criteria rules.
**Key insight**: Goal is evaluable granularity with quality checkpoints, not decomposition for its own sake.
### P3: Enhancement (Could Fix)
Incremental improvements for specific contexts.
#### BP-007: Biased Examples → Diverse Coverage
| Detection | Transform |
|-----------|-----------|
| All examples share same pattern/structure | Add edge cases and exceptions |
| Only happy-path examples | Add error cases, boundary conditions |
| Examples all same complexity | Include simple, moderate, and complex |
#### BP-008: No Uncertainty Permission → Explicit Escalation
| Detection | Transform |
|-----------|-----------|
| Skill demands definitive answers always | Add escalation criteria for ambiguous cases |
| No "when to stop" guidance | Add explicit stopping conditions |
**Skill example:**
- Before: "Determine the root cause"
- After: "Determine the root cause. If root cause is uncertain after 3 investigation cycles, report top 3 hypotheses with confidence levels and evidence for each."
## 9 Skill Editing Principles
Measurable quality criteria for skill content. Each principle includes a pass/fail test.
| # | Principle | Pass Criteria | Fail Example |
|---|-----------|---------------|--------------|
| 1 | Context efficiency | Every sentence contributes to LLM decision-making. No filler. | "This is an important skill that helps with..." |
| 2 | Deduplication | No concept explained twice at the same abstraction level within the skill or across skills. Mentions at different structural roles (e.g., classification framework vs execution detail) are not duplicates, provided the re-mention adds new constraints or criteria | Same error handling rules restated at the same abstraction level in multiple related skills |
| 3 | Grouping | Related criteria in single section (minimize read operations) | Scattered error handling rules across 4 sections |
| 4 | Measurability | All criteria use if-then format or concrete thresholds | "Write clean code" without definition of clean |
| 5 | Positive form | Instructions state what to do (BP-001 applied) | "Don't use any" instead of "Use only X" |
| 6 | Consistent notation | Uniform heading levels, list styles, table formats | Mix of `-`, `*`, `1.` in same context |
| 7 | Explicit prerequisites | All assumed knowledge stated | Uses "DI" without defining Dependency Injection |
| 8 | Priority ordering | Most important items first, exceptions last | Edge cases before common patterns |
| 9 | Scope boundaries | Explicit coverage: what this skill addresses vs references to other skills | Overlapping guidance with no cross-reference |
## References
- **Creating skills**: See [references/creation-guide.md](references/creation-guide.md) for generation flow and description guidelines
- **Reviewing skills**: See [references/review-criteria.md](references/review-criteria.md) for evaluation flow and grading
章节与文件索引
按说明文件中的顺序排列。
核心理念
P1:严重(必须修复)
P2:高影响(应该修复)
P3:增强(可以修复)
9 技能编辑原则
文件/命令 -> userId · ## Issues Found · operational/procedural · I/O · criteria/patterns · Context/Prerequisites · Process/Methodology · format/Examples
内容校验值 -> 1384cee24e57
当前原文的自动摘译,尚未人工审校。
核心理念
循证:以即时工程研究为基础,应用于技能创作 具体:每种模式都提供检测标准和转换方法 注重结构:优化表达和组织;领域知识保持不变
P1:严重(必须修复)
消耗技能时直接降低LLM执行准确性的问题。 BP-001:否定指令 → 肯定形式检测 · 转换技能指令中的“不要”、“不要”、“从不”、“避免” · 重新构建为具有同等约束的积极指令。例外:仅当满足所有 4 个条件时才允许使用否定形式:(1) 违规会在单个步骤中破坏状态,(2) 调用者或后续步骤无法正常恢复,(3) 约束是操作/程序性的,而不是质量策略或角色边界,(4) 正向重写会扩大或模糊目标范围。如果不满足任何条件,则以正数形式重写。
P2:高影响(应该修复)
解决后会降低技能效率的问题。 BP-004:非结构化内容 → 组织格式检测 · 转换没有标题的文本墙 · 应用标准部分顺序(见下文) 多个主题混合在一个部分中 · 分成不同的标题部分
P3:增强(可以修复)
针对特定环境的增量改进。 BP-007:有偏差的示例 → 多样化覆盖检测 · 转换 所有示例共享相同的模式/结构 · 添加边缘情况和异常 仅快乐路径示例 · 添加错误情况、边界条件
9 技能编辑原则
技能内容的可衡量的质量标准。每个原则都包含通过/失败测试。 · 原理 · 通过标准 · 失败示例 1 · 上下文效率 · 每句话都有助于 LLM 决策。无填充物。 · “这是一项重要的技能,有助于……” 2 · 重复数据删除 · 没有概念在技能内或跨技能的同一抽象级别上被解释两次。不同结构角色(例如,分类框架与执行细节)的提及不重复,前提是重新提及添加了新的约束或标准 · 在多个相关技能中的相同抽象级别重申相同的错误处理规则