update-skill-learnings
Skill15 starsChanged 8 months agoApache-2.0View on GitHub
Extract learnings about skill creation/improvement from a session and propagate them to the central skill learnings file, then sync to appropriate skills. Use when a session revealed patterns, anti-patterns, or insights about structuring skills. Invoke via /update-skill-learnings or after skill creation/improvement sessions.
In this repository63 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-browserSkill
- ast-grepSkill
- branch-review-before-prSkill
- browse-qaSkill
- browser-useSkill
- browseSkill
- bugfixSkill
- build-dmgSkill
- claude-reviewSkill
- codemapSkill
- code-simplifySkill
- codex-reviewSkill
- commitSkill
- cost-estimateSkill
- create-prSkill
- find-agentsSkill
- find-bugsSkill
- frontend-design-ui-uxSkill
- git-merge-expertSkill
- git-merge-expert-worktreeSkill
- kiro-reviewSkill
- laravel-filamentSkill
- laravelSkill
- lokeiSkill
- map-project-monorepoSkill
- map-projectSkill
- nextjsSkill
- plan-founder-reviewSkill
- plan-to-task-list-with-dagSkill
- pr-retroSkill
- run-parallel-agents-feature-buildSkill
- run-parallel-agents-feature-debugSkill
- rustSkill
- secretsSkill
- startSkill
- update-agent-learningsSkill
- update-claude-learningsSkill
- update-claude-settingsSkill
- ast-grepSkill
- branch-review-before-prSkill
- codemapSkill
- code-simplifySkill
- commitSkill
- cost-estimateSkill
- create-prSkill
- find-bugsSkill
- frontend-design-ui-uxSkill
- git-merge-expertSkill
- git-merge-expert-worktreeSkill
- map-project-monorepoSkill
- map-projectSkill
- plan-founder-reviewSkill
- plan-to-task-list-with-dagSkill
- pr-retroSkill
- run-parallel-agents-feature-buildSkill
- run-parallel-agents-feature-debugSkill
- startSkill
- update-agent-learningsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 12 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Before adding ANY skill learning, you ABSOLUTELY MUST:
- Distinctive: line 11
Verify the pattern is about skill structure/content (not application code)
- Distinctive: line 24
Before adding ANY skill learning, you MUST complete this checklist:
- Distinctive: line 54
After creating a new skill
- Distinctive: line 55
After improving an existing skill
- Distinctive: line 56
After reviewing skill quality (like the ulpi-generate-hooks review)
- Distinctive: line 57
When discovering patterns that make skills more effective
- Distinctive: line 60
Never add learnings proactively: Only when session revealed concrete patterns.
- Distinctive: line 140
Add new learnings to the appropriate section
- Distinctive: line 141
Update the "Last updated" timestamp
- Distinctive: line 301
Fix: Search existing learnings before adding
- Distinctive: line 347
When update is complete, announce:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<EXTREMELY-IMPORTANT>
Before adding ANY skill learning, you **ABSOLUTELY MUST**:- Identify a concrete, actionable pattern (not vague observation)
- Verify the pattern is about skill structure/content (not application code)
- Categorize correctly: Structural Pattern, Content Pattern, Anti-Pattern, or Skill-Specific
- Get user confirmation before writing
Adding learnings without verification = cluttered, unhelpful knowledge base
This is not optional. Every learning requires disciplined validation.
</EXTREMELY-IMPORTANT>
Update Skill Learnings
MANDATORY FIRST RESPONSE PROTOCOL
Before adding ANY skill learning, you MUST complete this checklist:
- ☐ Identify the specific pattern or anti-pattern from the session
- ☐ Verify this is about skill creation/improvement (not application code)
- ☐ Categorize: Structural, Content, Anti-Pattern, or Skill-Specific
- ☐ Formulate as actionable guidance (imperative mood)
- ☐ Check for duplicates in existing learnings
- ☐ Present learning to user for confirmation
- ☐ Announce: "Adding skill learning: [category] - [brief description]"
Adding learnings WITHOUT completing this checklist = noise in the knowledge base.
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
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.
Step 1: Session Analysis
Gate: Identify at least one concrete skill pattern before proceeding to Step 2.
Review the current conversation/session for skill-related patterns:
- Structural discoveries:
- What sections were missing from a skill?
- What structural patterns made skills more effective?
- What formatting improved clarity?
- Content discoveries:
- What made instructions clearer?
- What examples helped understanding?
- What error handling was missing?
- Anti-patterns discovered:
- What caused confusion or errors?
- What was missing that caused problems?
- What patterns should be avoided?
Step 2: Learning Extraction
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
Learning Classification
Each learning should specify:
| Field | Options | Description |
| Category | Structural Patterns, Content Patterns, Anti-Patterns, Skill-Specific | Where does this learning fit? |
| Subcategory | Required Sections, Quality Signals, Clarity, User Interaction, Structure, Content | More specific placement |
Classification Guide
| Category | What It Covers | Examples |
| Structural Patterns | Required sections, file organization, quality signals | EXTREMELY-IMPORTANT block, Gate checkpoints, Quality Checklist |
| Content Patterns | Writing style, clarity, examples, user interaction | Imperative mood, concrete examples, error handling |
| Anti-Patterns | Things to avoid in skills | Missing gates, vague instructions, no failure modes |
| Skill-Specific | Learnings about one particular skill | ulpi-generate-hooks needs same patterns as commit |
Step 3: Update Central Learnings File
Gate: Learnings file updated successfully before proceeding to Step 4.
- Read current
.claude/learnings/skill-learnings.md - 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
- Structural patterns go under
- Add new learnings to the appropriate section
- Update the "Last updated" timestamp
- Write updated file
File Structure
The learnings file follows this structure:
# Skill Learnings
## Structural Patterns
### Required Sections
- [learning items...]
### Quality Signals
- [learning items...]
---
## Content Patterns
### Clarity
- [learning items...]
### User Interaction
- [learning items...]
---
## Anti-Patterns
### Structure
- [learning items...]
### Content
- [learning items...]
---
## Skill-Specific Learnings
### [skill-name]
- [learning specific to this skill...]
---
*Last updated: [date]*Step 4: Verification
Gate: All checks pass before marking complete.
Check 1: Learning Added
- New learning appears in correct section
- No duplicate entries created
- Timestamp updated
Check 2: Learning Quality
- Learning is actionable (imperative mood)
- Learning is specific (not vague)
- Learning includes context if needed
Check 3: File Integrity
- File structure preserved
- No sections accidentally removed
- Markdown formatting valid
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
| Situation | Action |
| Learning is vague | Refine to be actionable before adding |
| Learning is about application code | Redirect to update-agent-learnings |
| Category unclear | Ask user to clarify |
| Duplicate exists | Merge or skip, inform user |
| File structure broken | Fix structure before adding |
Safety Rules
| Rule | Reason |
| Always get user confirmation | Ensures learnings are accurate and desired |
| Never delete existing learnings | Preserve institutional knowledge |
| Keep learnings actionable | Vague observations don't help |
| Use imperative mood | Clearer instructions |
| Preserve file structure | Maintains organization |
Quality Checklist (Must Score 8/10)
Score yourself honestly before marking update complete:
Learning Identification (0-2 points)
- 0 points: Vague observation, not actionable
- 1 point: Somewhat specific but could be clearer
- 2 points: Concrete, actionable pattern
Classification (0-2 points)
- 0 points: Wrong category
- 1 point: Correct category, wrong subcategory
- 2 points: Correct category and subcategory
User Confirmation (0-2 points)
- 0 points: Added without showing to user
- 1 point: Showed but didn't wait for confirmation
- 2 points: Full confirmation before writing
File Integrity (0-2 points)
- 0 points: Broke file structure
- 1 point: Minor formatting issues
- 2 points: Clean update, structure preserved
Duplicate Check (0-2 points)
- 0 points: Added duplicate without checking
- 1 point: Checked but not thoroughly
- 2 points: Verified no duplicates exist
Minimum passing score: 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
Symptom: Learnings like "skills should be clear" Fix: Be specific - "Use imperative mood, provide concrete examples"
Failure Mode 2: Wrong Category
Symptom: Structural pattern filed under Anti-Patterns Fix: Review category definitions before filing
Failure Mode 3: Duplicate Added
Symptom: Same learning exists in multiple places Fix: Search existing learnings before adding
Failure Mode 4: Application Code Learning
Symptom: Learning about TypeScript patterns added to skill learnings Fix: Redirect to update-agent-learnings skill
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 passCompletion 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.Integration with Other Skills
The update-skill-learnings skill integrates with:
update-agent-learnings— Use for application code learnings, not skill learningscommit— Commit skill-learnings.md changes after updateskill-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 learningsDecision Guide:
Is the learning about...
│
┌────┴────┐
▼ ▼
Skills? Application Code?
│ │
▼ ▼
This skill update-agent-learningsExamples
Example 1: Adding a Structural Pattern Learning
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:
- Added to
.claude/learnings/skill-learnings.mdunder Structural Patterns → Required Sections
Example 2: Adding an Anti-Pattern
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:
- Added to
.claude/learnings/skill-learnings.mdunder Anti-Patterns → Content
Example 3: Adding a Skill-Specific Learning
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:
- Added to
.claude/learnings/skill-learnings.mdunder Skill-Specific Learnings → ulpi-generate-hooks
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

