Back to Details

update-skill-learnings

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<EXTREMELY-IMPORTANT> Before adding ANY skill learning, you **ABSOLUTELY MUST**:
  1. Identify a concrete, actionable pattern (not vague observation)
  2. Verify the pattern is about skill structure/content (not application code)
  3. Categorize correctly: Structural Pattern, Content Pattern, Anti-Pattern, or Skill-Specific
  4. Get user confirmation before writing
Adding learnings without verification = cluttered, unhelpful knowledge base
This is not optional. Every learning requires disciplined validation. </EXTREMELY-IMPORTANT>
<EXTREMELY-IMPORTANT> 在添加任何技能学习经验之前，你**必须**：
  1. 识别出具体、可落地的模式（而非模糊的观察结论）
  2. 验证该模式是关于技能结构/内容的（而非应用代码）
  3. 正确分类：Structural Pattern、Content Pattern、Anti-Pattern或Skill-Specific
  4. 写入前获得用户确认
未经验证就添加经验会导致知识库杂乱无章、毫无用处
这是强制性要求。每一条经验都需要经过严谨的验证。 </EXTREMELY-IMPORTANT>

Update Skill Learnings

更新技能学习经验

MANDATORY FIRST RESPONSE PROTOCOL

强制初始响应协议

Before adding ANY skill learning, you MUST complete this checklist:
  1. ☐ Identify the specific pattern or anti-pattern from the session
  2. ☐ Verify this is about skill creation/improvement (not application code)
  3. ☐ Categorize: Structural, Content, Anti-Pattern, or Skill-Specific
  4. ☐ Formulate as actionable guidance (imperative mood)
  5. ☐ Check for duplicates in existing learnings
  6. ☐ Present learning to user for confirmation
  7. ☐ Announce: "Adding skill learning: [category] - [brief description]"
Adding learnings WITHOUT completing this checklist = noise in the knowledge base.
在添加任何技能学习经验之前，你必须完成以下检查清单：
  1. ☐ 从会话中识别出具体的模式或反模式
  2. ☐ 验证该内容是关于技能创建/改进的（而非应用代码）
  3. ☐ 进行分类：Structural、Content、Anti-Pattern或Skill-Specific
  4. ☐ 将其整理为可落地的指导（使用祈使语气）
  5. ☐ 检查现有经验中是否存在重复内容
  6. ☐ 将经验呈现给用户以获取确认
  7. ☐ 发布通知："添加技能学习经验：[分类] - [简要描述]"
未完成此检查清单就添加经验会导致知识库产生无效信息。

Purpose

目的

This skill captures learnings about creating and improving Claude Code skills.
What it captures:
  • Structural patterns (required sections, quality signals)
  • Content patterns (clarity, user interaction)
  • Anti-patterns to avoid
  • Skill-specific learnings
Output: Updates to 
.claude/learnings/skill-learnings.md
→ synced to appropriate skills
Does NOT:
  • Capture learnings about application code (use update-agent-learnings instead)
  • Modify existing skills without user confirmation
本技能用于捕获创建和改进Claude Code技能的相关经验。
捕获内容包括：
  • Structural patterns：必填章节、质量标识
  • Content patterns：表述清晰度、用户交互
  • 需避免的Anti-patterns
  • 特定技能相关经验
输出结果： 更新
.claude/learnings/skill-learnings.md
文件 → 同步至对应的技能
不包括：
  • 捕获应用代码相关经验（请使用update-agent-learnings技能）
  • 未获得用户确认就修改现有技能

When to Use

使用场景

  • After creating a new skill
  • After improving an existing skill
  • After reviewing skill quality (like the ulpi-generate-hooks review)
  • When discovering patterns that make skills more effective
  • Invoke via 
    /update-skill-learnings
Never add learnings proactively. Only when session revealed concrete patterns.
  • 创建新技能之后
  • 改进现有技能之后
  • 审核技能质量之后（例如ulpi-generate-hooks审核）
  • 发现可提升技能有效性的模式时
  • 通过
    /update-skill-learnings
    命令调用
切勿主动添加经验。仅当会话揭示了具体模式时才可操作。

Step 1: Session Analysis

步骤1：会话分析

Gate: Identify at least one concrete skill pattern before proceeding to Step 2.
Review the current conversation/session for skill-related patterns:
  1. Structural discoveries:
    • What sections were missing from a skill?
    • What structural patterns made skills more effective?
    • What formatting improved clarity?
  2. Content discoveries:
    • What made instructions clearer?
    • What examples helped understanding?
    • What error handling was missing?
  3. Anti-patterns discovered:
    • What caused confusion or errors?
    • What was missing that caused problems?
    • What patterns should be avoided?
准入条件：至少识别出一个具体的技能模式，才可进入步骤2。
回顾当前对话/会话，查找与技能相关的模式：
  1. 结构发现：
    • 技能缺失了哪些章节？
    • 哪些结构模式提升了技能的有效性？
    • 哪些格式改进了内容清晰度？
  2. 内容发现：
    • 哪些因素让说明更清晰？
    • 哪些示例有助于理解？
    • 缺失了哪些错误处理机制？
  3. 发现的反模式：
    • 哪些因素导致了混淆或错误？
    • 缺失了哪些内容从而引发问题？
    • 哪些模式应避免使用？

Step 2: Learning Extraction

步骤2：经验提取

Gate: User confirms extracted learnings before proceeding to Step 3.
Present findings to user and ask for confirmation:
I identified the following skill learnings from this session:

**Structural Patterns:**
1. [Pattern description]

**Content Patterns:**
1. [Pattern description]

**Anti-Patterns:**
1. [Pattern description]

**Skill-Specific (if any):**
1. [Skill name]: [Learning description]

Should I add these to the skill learnings file?
Use AskUserQuestion to:
  • Confirm the extracted learnings are accurate
  • Allow user to refine or add additional learnings
  • Get approval before making changes
准入条件：用户确认提取的经验后，才可进入步骤3。
将发现结果呈现给用户并请求确认：
我从本次会话中识别出以下技能学习经验：

**Structural Patterns：**
1. [模式描述]

**Content Patterns：**
1. [模式描述]

**Anti-Patterns：**
1. [模式描述]

**Skill-Specific（如有）：**
1. [技能名称]：[经验描述]

是否应将这些添加到技能学习文件中？
使用AskUserQuestion工具：
  • 确认提取的经验是否准确
  • 允许用户优化或添加额外经验
  • 在进行修改前获得批准

Learning Classification

经验分类

Each learning should specify:
FieldOptionsDescription
CategoryStructural Patterns, Content Patterns, Anti-Patterns, Skill-SpecificWhere does this learning fit?
SubcategoryRequired Sections, Quality Signals, Clarity, User Interaction, Structure, ContentMore specific placement
每条经验应明确以下信息：
字段选项描述
CategoryStructural Patterns、Content Patterns、Anti-Patterns、Skill-Specific该经验所属类别
SubcategoryRequired Sections、Quality Signals、Clarity、User Interaction、Structure、Content更具体的分类

Classification Guide

分类指南

CategoryWhat It CoversExamples
Structural PatternsRequired sections, file organization, quality signalsEXTREMELY-IMPORTANT block, Gate checkpoints, Quality Checklist
Content PatternsWriting style, clarity, examples, user interactionImperative mood, concrete examples, error handling
Anti-PatternsThings to avoid in skillsMissing gates, vague instructions, no failure modes
Skill-SpecificLearnings about one particular skillulpi-generate-hooks needs same patterns as commit
类别覆盖范围示例
Structural Patterns必填章节、文件组织、质量标识EXTREMELY-IMPORTANT块、Gate检查点、Quality Checklist
Content Patterns写作风格、清晰度、示例、用户交互祈使语气、具体示例、错误处理
Anti-Patterns技能中需避免的内容缺失Gate检查、模糊说明、未定义失败模式
Skill-Specific针对特定技能的经验ulpi-generate-hooks需遵循与commit相同的模式

Step 3: Update Central Learnings File

步骤3：更新中央学习文件

Gate: Learnings file updated successfully before proceeding to Step 4.
  1. Read current 
    .claude/learnings/skill-learnings.md
  2. Locate the appropriate section:
    • Structural patterns go under 
      ## Structural Patterns
      → appropriate subsection
    • Content patterns go under 
      ## Content Patterns
      → appropriate subsection
    • Anti-patterns go under 
      ## Anti-Patterns
      → appropriate subsection
    • Skill-specific learnings go under 
      ## Skill-Specific Learnings
      → appropriate skill
  3. Add new learnings to the appropriate section
  4. Update the "Last updated" timestamp
  5. Write updated file
准入条件：成功更新学习文件后，才可进入步骤4。
  1. 读取当前的
    .claude/learnings/skill-learnings.md
    文件
  2. 定位到对应的章节：
    • Structural patterns放入
      ## Structural Patterns
      下的对应子章节
    • Content patterns放入
      ## Content Patterns
      下的对应子章节
    • Anti-patterns放入
      ## Anti-Patterns
      下的对应子章节
    • 特定技能经验放入
      ## Skill-Specific Learnings
      下的对应技能章节
  3. 将新经验添加到对应章节
  4. 更新“Last updated”时间戳
  5. 写入更新后的文件

File Structure

文件结构

The learnings file follows this structure:
markdown
undefined
学习文件遵循以下结构：
markdown
undefined

Skill Learnings

Skill Learnings

Structural Patterns

Structural Patterns

Required Sections

Required Sections

  • [learning items...]
  • [学习条目...]

Quality Signals

Quality Signals

  • [learning items...]
  • [学习条目...]

Content Patterns

Content Patterns

Clarity

Clarity

  • [learning items...]
  • [学习条目...]

User Interaction

User Interaction

  • [learning items...]
  • [学习条目...]

Anti-Patterns

Anti-Patterns

Structure

Structure

  • [learning items...]
  • [学习条目...]

Content

Content

  • [learning items...]
  • [学习条目...]

Skill-Specific Learnings

Skill-Specific Learnings

[skill-name]

[skill-name]

  • [learning specific to this skill...]
Last updated: [date]
undefined
  • [该技能的特定学习经验...]
Last updated: [date]
undefined

Step 4: Verification

步骤4：验证

Gate: All checks pass before marking complete.
准入条件：所有检查项通过后，才可标记任务完成。

Check 1: Learning Added

检查1：经验已添加

  • New learning appears in correct section
  • No duplicate entries created
  • Timestamp updated
  • 新经验出现在正确的章节中
  • 未创建重复条目
  • 时间戳已更新

Check 2: Learning Quality

检查2：经验质量

  • Learning is actionable (imperative mood)
  • Learning is specific (not vague)
  • Learning includes context if needed
  • 经验可落地（使用祈使语气）
  • 经验具体明确（而非模糊表述）
  • 必要时经验包含上下文信息

Check 3: File Integrity

检查3：文件完整性

  • File structure preserved
  • No sections accidentally removed
  • Markdown formatting valid
  • 文件结构得以保留
  • 未意外删除任何章节
  • Markdown格式有效

Pre-Update Checklist

更新前检查清单

Before updating, verify:
  • Learning is concrete and actionable
  • Learning is about skills (not application code)
  • Category assignment is correct
  • No duplicates exist
  • User confirmed the learning
更新前，请验证：
  • 经验具体且可落地
  • 经验是关于技能的（而非应用代码）
  • 分类分配正确
  • 不存在重复内容
  • 用户已确认该经验

Error Handling

错误处理

SituationAction
Learning is vagueRefine to be actionable before adding
Learning is about application codeRedirect to update-agent-learnings
Category unclearAsk user to clarify
Duplicate existsMerge or skip, inform user
File structure brokenFix structure before adding
场景操作
经验表述模糊在添加前优化为可落地的内容
经验是关于应用代码的引导至update-agent-learnings技能
分类不明确询问用户以明确分类
存在重复内容合并或跳过，并通知用户
文件结构损坏在添加前修复结构

Safety Rules

安全规则

RuleReason
Always get user confirmationEnsures learnings are accurate and desired
Never delete existing learningsPreserve institutional knowledge
Keep learnings actionableVague observations don't help
Use imperative moodClearer instructions
Preserve file structureMaintains organization
规则原因
始终获取用户确认确保经验准确且符合需求
切勿删除现有经验保留机构知识资产
保持经验可落地模糊的观察结论毫无帮助
使用祈使语气说明更清晰
保留文件结构维持文件的组织性

Quality Checklist (Must Score 8/10)

质量检查清单（需达到8/10分）

Score yourself honestly before marking update complete:
在标记更新完成前，请如实自评：

Learning Identification (0-2 points)

经验识别（0-2分）

  • 0 points: Vague observation, not actionable
  • 1 point: Somewhat specific but could be clearer
  • 2 points: Concrete, actionable pattern
  • 0分： 模糊的观察结论，不可落地
  • 1分： 较为具体但表述可更清晰
  • 2分： 具体、可落地的模式

Classification (0-2 points)

分类（0-2分）

  • 0 points: Wrong category
  • 1 point: Correct category, wrong subcategory
  • 2 points: Correct category and subcategory
  • 0分： 分类错误
  • 1分： 分类正确，但子分类错误
  • 2分： 分类和子分类均正确

User Confirmation (0-2 points)

用户确认（0-2分）

  • 0 points: Added without showing to user
  • 1 point: Showed but didn't wait for confirmation
  • 2 points: Full confirmation before writing
  • 0分： 未呈现给用户就添加
  • 1分： 已呈现但未等待确认
  • 2分： 写入前获得完整确认

File Integrity (0-2 points)

文件完整性（0-2分）

  • 0 points: Broke file structure
  • 1 point: Minor formatting issues
  • 2 points: Clean update, structure preserved
  • 0分： 破坏了文件结构
  • 1分： 存在轻微格式问题
  • 2分： 更新干净，结构得以保留

Duplicate Check (0-2 points)

重复检查（0-2分）

  • 0 points: Added duplicate without checking
  • 1 point: Checked but not thoroughly
  • 2 points: Verified no duplicates exist
Minimum passing score: 8/10
  • 0分： 未检查就添加了重复内容
  • 1分： 已检查但不彻底
  • 2分： 确认不存在重复内容
最低合格分数：8/10

Common Rationalizations (All Wrong)

常见错误理由（均不成立）

These are excuses. Don't fall for them:
  • "This pattern is obvious" → STILL document it explicitly
  • "It's just a small insight" → Small insights compound into quality
  • "The learnings file is already comprehensive" → STILL check for gaps
  • "The user knows what they want" → STILL confirm before adding
  • "This is similar to an existing learning" → Check if it's a duplicate or refinement
这些都是借口，请勿采纳：
  • “这个模式很明显” → 仍需明确记录
  • “这只是一个小见解” → 小见解积累起来可提升质量
  • “学习文件已经很全面了” → 仍需检查是否存在遗漏
  • “用户知道自己想要什么” → 仍需在添加前确认
  • “这与现有经验类似” → 检查是否为重复内容或可优化项

Failure Modes

失败模式

Failure Mode 1: Vague Learnings

失败模式1：模糊的经验

Symptom: Learnings like "skills should be clear" Fix: Be specific - "Use imperative mood, provide concrete examples"
症状： 类似“技能应清晰明了”的经验 修复方案： 具体化表述 - “使用祈使语气，提供具体示例”

Failure Mode 2: Wrong Category

失败模式2：分类错误

Symptom: Structural pattern filed under Anti-Patterns Fix: Review category definitions before filing
症状： 将结构模式归类到反模式中 修复方案： 归档前回顾分类定义

Failure Mode 3: Duplicate Added

失败模式3：添加重复内容

Symptom: Same learning exists in multiple places Fix: Search existing learnings before adding
症状： 同一经验出现在多个位置 修复方案： 添加前搜索现有经验

Failure Mode 4: Application Code Learning

失败模式4：添加应用代码相关经验

Symptom: Learning about TypeScript patterns added to skill learnings Fix: Redirect to update-agent-learnings skill
症状： 将TypeScript模式相关经验添加到技能学习文件中 修复方案： 引导至update-agent-learnings技能

Quick Workflow Summary

工作流快速总结

STEP 1: SESSION ANALYSIS
├── Review session for skill patterns
├── Identify structural discoveries
├── Identify content discoveries
├── Identify anti-patterns
└── Gate: Concrete pattern identified

STEP 2: LEARNING EXTRACTION
├── Categorize the learning
├── Formulate as actionable guidance
├── Check for duplicates
├── Present to user
├── Get confirmation
└── Gate: User approved

STEP 3: UPDATE LEARNINGS FILE
├── Read current skill-learnings.md
├── Locate correct section
├── Add new learning
├── Update timestamp
├── Write file
└── Gate: File updated

STEP 4: VERIFICATION
├── Verify learning added correctly
├── Verify learning quality
├── Verify file integrity
└── Gate: All checks pass
步骤1：会话分析
├── 回顾会话以查找技能模式
├── 识别结构发现
├── 识别内容发现
├── 识别反模式
└── 准入条件：已识别具体模式

步骤2：经验提取
├── 对经验进行分类
├── 整理为可落地的指导
├── 检查重复内容
├── 呈现给用户
├── 获取确认
└── 准入条件：用户已批准

步骤3：更新学习文件
├── 读取当前的skill-learnings.md
├── 定位到正确章节
├── 添加新经验
├── 更新时间戳
├── 写入文件
└── 准入条件：文件已更新

步骤4：验证
├── 验证经验已正确添加
├── 验证经验质量
├── 验证文件完整性
└── 准入条件：所有检查项通过

Completion Announcement

完成通知

When update is complete, announce:
Skill learning added.

**Quality Score: X/10**
- Learning Identification: X/2
- Classification: X/2
- User Confirmation: X/2
- File Integrity: X/2
- Duplicate Check: X/2

**Learning Added:**
- Category: [category]
- Subcategory: [subcategory]
- Learning: [brief description]

**File Updated:** .claude/learnings/skill-learnings.md

**Next steps:**
Review the skill-learnings.md file to see all captured patterns.
更新完成后，发布以下通知：
已添加技能学习经验。

**质量评分：X/10**
- 经验识别：X/2
- 分类：X/2
- 用户确认：X/2
- 文件完整性：X/2
- 重复检查：X/2

**添加的经验：**
- 分类：[分类]
- 子分类：[子分类]
- 经验：[简要描述]

**已更新文件：** .claude/learnings/skill-learnings.md

**后续步骤：**
查看skill-learnings.md文件以查看所有已捕获的模式。

Integration with Other Skills

与其他技能的集成

The 
update-skill-learnings
skill integrates with:
  • update-agent-learnings
     — Use for application code learnings, not skill learnings
  • commit
     — Commit skill-learnings.md changes after update
  • skill-creator
    (example-skills)     — Reference skill-learnings.md when creating new skills
Workflow Chain:
Session reveals skill pattern
         │
         ▼
update-skill-learnings skill (this skill)
         │
         ▼
skill-learnings.md updated
         │
         ▼
Future skill creation benefits from learnings
Decision Guide:
Is the learning about...
         │
    ┌────┴────┐
    ▼         ▼
Skills?   Application Code?
    │         │
    ▼         ▼
This skill   update-agent-learnings
update-skill-learnings
技能可与以下技能集成：
  • update-agent-learnings
     — 用于应用代码相关经验，而非技能经验
  • commit
     — 更新后提交skill-learnings.md的变更
  • skill-creator
    （example-skills）     — 创建新技能时参考skill-learnings.md
工作流链：
会话揭示技能模式
         │
         ▼
update-skill-learnings技能（本技能）
         │
         ▼
skill-learnings.md已更新
         │
         ▼
未来的技能创建可受益于这些经验
决策指南：
该经验是否关于...
         │
    ┌────┴────┐
    ▼         ▼
技能？   应用代码？
    │         │
    ▼         ▼
使用本技能   使用update-agent-learnings

Examples

示例

Example 1: Adding a Structural Pattern Learning

示例1：添加结构模式经验

Session Issue: Created a skill without EXTREMELY-IMPORTANT block.
Learning Extraction:
  • Category: Structural Patterns
  • Subcategory: Required Sections
  • Learning: "Always include 
    <EXTREMELY-IMPORTANT>
    block after frontmatter with verification requirements"
Result:
  1. Added to 
    .claude/learnings/skill-learnings.md
    under Structural Patterns → Required Sections
会话问题： 创建技能时未包含EXTREMELY-IMPORTANT块。
提取的经验：
  • 分类：Structural Patterns
  • 子分类：Required Sections
  • 经验：“始终在前置内容后包含
    <EXTREMELY-IMPORTANT>
    块，并注明验证要求”
结果：
  1. 添加到
    .claude/learnings/skill-learnings.md
    的Structural Patterns → Required Sections章节下

Example 2: Adding an Anti-Pattern

示例2：添加反模式经验

Session Issue: Skill had bash code blocks that looked executable but were meant as instructions.
Learning Extraction:
  • Category: Anti-Patterns
  • Subcategory: Content
  • Learning: "Avoid bash code blocks that look executable but are meant as agent instructions - rephrase as prose"
Result:
  1. Added to 
    .claude/learnings/skill-learnings.md
    under Anti-Patterns → Content
会话问题： 技能中的bash代码块看似可执行，但实际仅为说明。
提取的经验：
  • 分类：Anti-Patterns
  • 子分类：Content
  • 经验：“避免使用看似可执行但实际为Agent说明的bash代码块 - 改用散文式表述”
结果：
  1. 添加到
    .claude/learnings/skill-learnings.md
    的Anti-Patterns → Content章节下

Example 3: Adding a Skill-Specific Learning

示例3：添加特定技能经验

Session Issue: ulpi-generate-hooks was missing patterns that commit/create-pr/start have.
Learning Extraction:
  • Category: Skill-Specific
  • Skill: ulpi-generate-hooks
  • Learning: "Apply same structural patterns as commit/create-pr/start for consistency"
Result:
  1. Added to 
    .claude/learnings/skill-learnings.md
    under Skill-Specific Learnings → ulpi-generate-hooks
会话问题： ulpi-generate-hooks缺失了与commit/create-pr/start相同的模式。
提取的经验：
  • 分类：Skill-Specific
  • 技能：ulpi-generate-hooks
  • 经验：“为保持一致性，应用与commit/create-pr/start相同的结构模式”
结果：
  1. 添加到
    .claude/learnings/skill-learnings.md
    的Skill-Specific Learnings → ulpi-generate-hooks章节下