update-agent-learnings
Skill15 starsChanged 8 months agoApache-2.0View on GitHub
Extract learnings from a session and propagate them to appropriate agent files based on scope (Global for all subagents, Claude Code Only for main agent, or Agent-Specific). Use when a session revealed patterns, mistakes, or insights. Invoke via /update-agent-learnings or after challenging 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-claude-learningsSkill
- update-claude-settingsSkill
- update-skill-learningsSkill
- 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
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 10 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
After a challenging session where things went wrong
- Distinctive: line 25
When patterns emerge that should inform future behavior
- Distinctive: line 26
After discovering anti-patterns or better approaches
- Distinctive: line 27
When user provides feedback about agent behavior
- Distinctive: line 119
Add new learnings to the appropriate section
- Very specific: line 187
All content under ## Global Learnings (all categories: Scope Control, Session Management, etc.) → Propagate to ALL subagents
- Very specific: line 188
All content under ## Agent-Specific Learnings (per-agent subsections) → Propagate to THAT agent only
- Very specific: line 189
All content under ## Claude Code Only Learnings → DO NOT propagate to any subagent files
- Distinctive: line 207
Do NOT just append - regenerate the full section to ensure consistency
- Distinctive: line 209
Verify the edit was successful: before moving to next agent
- Very specific: line 214
AFTER ## Rules (and any subsections like ### AWS Security Best Practices)
- Distinctive: line 217
Use this pattern to locate insertion point:
- Very specific: line 326
Run this command to verify ALL agent files have the ## Learnings section:
- Distinctive: line 334
If the count is less than 9, identify which files are missing and fix them.
- Distinctive: line 369
Before marking the update complete, verify:
≈ “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
Update Agent Learnings
Overview
Extract learnings from the current session and systematically propagate them to:
- The central learnings repository (
.claude/learnings/agent-learnings.md) - Appropriate agent files based on learning scope
IMPORTANT: Not all learnings apply to all agents.
- Subagent learnings (Global, Agent-Specific): Apply to specialized engineer agents that write application code
- Claude Code learnings: Apply only to the main Claude Code agent, NOT propagated to subagents
This creates a feedback loop that improves agent behavior over time based on real-world session outcomes.
When to Use
- After a challenging session where things went wrong
- When patterns emerge that should inform future behavior
- After discovering anti-patterns or better approaches
- When user provides feedback about agent behavior
- Invoke via
/update-learningscommand
Phase 1: Session Analysis
Gate: Identify at least one concrete learning before proceeding.
Review the current conversation/session:
- Identify challenges encountered:
- What problems occurred during the session?
- What mistakes were made?
- What took multiple attempts to get right?
- Look for patterns:
- Over-scoping (changing more than requested)
- Session management issues (premature endings, lost context)
- Coordination problems (subagent noise, focus issues)
- Testing gaps (missing validation, broken tests)
- Scope creep (tangential work)
- Categorize findings:
- Is this a global learning (applies to ALL agents)?
- Is this agent-specific (only relevant to one type of agent)?
Phase 2: Learning Extraction
Gate: User confirms extracted learnings before proceeding.
Present findings to user and ask for confirmation:
I identified the following learnings from this session:
**Global Learnings:**
1. [Category]: [Learning description]
- Action type: Always/Never/Prefer
**Agent-Specific Learnings (if any):**
1. [Agent name]: [Learning description]
Should I add these to the learnings system?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 | Scope Control, Session Management, Multi-Agent Coordination, Autonomous Iteration, Testing Integration, Other | Where does this learning fit? |
| Scope | Global, Claude Code Only, or [Agent Name] | Who does this learning apply to? |
| Action Type | Always, Never, Prefer | How strong is the directive? |
Scope Decision Guide
CRITICAL: Choose the correct scope. Not all learnings belong in subagent files.
| Scope | When to Use | Propagate to Subagents? |
| Global | Learnings about writing code, testing, debugging, scope control | ✅ Yes - all subagents |
| Claude Code Only | Learnings about skills, agents, configuration files, orchestration | ❌ No - main agent only |
| [Agent Name] | Learnings specific to one technology/framework | ✅ Yes - that agent only |
Examples of Claude Code Only learnings (DO NOT propagate to subagents):
- Improving skills or configuration files
- Creating or modifying agent definitions
- Orchestrating multiple subagents
- Working with CLAUDE.md or project setup
- Meta-level patterns about how Claude Code works
Examples of Global learnings (DO propagate to subagents):
- Scope control when writing application code
- Testing practices for code changes
- Session management and checkpointing
- Multi-agent coordination as a subagent
Ask yourself: "Would a nodejs-cli-senior-engineer or fastapi-senior-engineer need this learning while writing application code?" If no, it's Claude Code Only.
Phase 3: Update Central Learnings File
Gate: Learnings file updated successfully before proceeding.
- Read current
.claude/learnings/agent-learnings.md - Locate the appropriate section:
- Global learnings go under
## Global Learnings→ appropriate category - Agent-specific learnings go under
## Agent-Specific Learnings→ appropriate agent
- Global learnings go under
- Add new learnings to the appropriate section
- Write updated file
File Structure
The learnings file should follow this structure:
# Agent Learnings
## Global Learnings
These learnings apply to ALL subagents and should be synced to every agent file.
### Scope Control
- [learning items...]
### Session Management
- [learning items...]
### Multi-Agent Coordination
- [learning items...]
### Autonomous Iteration
- [learning items...]
### Testing Integration
- [learning items...]
---
## Claude Code Only Learnings
These learnings apply ONLY to the main Claude Code agent. DO NOT propagate to subagent files.
### Skills & Configuration
- [learnings about creating/improving skills, agents, configs...]
### Orchestration
- [learnings about coordinating subagents, workflows...]
### Project Setup
- [learnings about CLAUDE.md, project initialization...]
---
## Agent-Specific Learnings
### nodejs-cli-senior-engineer
- [learning specific to this agent...]
### nextjs-senior-engineer
- [learning specific to this agent...]
[...other agents as needed...]Phase 4: Propagate to Agents
Gate: All agent files updated before proceeding.
CRITICAL: This phase requires a FULL SYNC of the ## Learnings section, not just adding new learnings.
IMPORTANT: Only propagate learnings that apply to subagents. Skip "Claude Code Only" learnings.
Step 4.1: Read Central Learnings
First, read .claude/learnings/agent-learnings.md and extract:
- All content under
## Global Learnings(all categories: Scope Control, Session Management, etc.) → Propagate to ALL subagents - All content under
## Agent-Specific Learnings(per-agent subsections) → Propagate to THAT agent only - All content under
## Claude Code Only Learnings→ DO NOT propagate to any subagent files
Step 4.2: Process Each Agent File
For each agent in .claude/agents/:
- Read the agent file completely
- Check if
## Learningssection exists by searching for the heading## Learnings - If
## Learningssection is MISSING:- Find the
## Examplessection - Insert a complete
## Learningssection BEFORE## Examples - The section must contain ALL global learnings from the central file
- Include any agent-specific learnings for this agent
- Find the
- If
## Learningssection EXISTS:- Replace the ENTIRE section content with fresh sync from central file
- Do NOT just append - regenerate the full section to ensure consistency
- Verify the edit was successful before moving to next agent
Step 4.3: Section Placement
The ## Learnings section MUST be placed:
- AFTER
## Rules(and any subsections like### AWS Security Best Practices) - BEFORE
## Examples
Use this pattern to locate insertion point:
---
## ExamplesInsert the Learnings section just before this pattern.
Agent Learnings Section Format
IMPORTANT: Generate this COMPLETE section for each agent. Do not skip any categories.
---
## Learnings
> Auto-synced from `.claude/learnings/agent-learnings.md`
### Global Learnings
#### Scope Control
**Always:**
- Confirm scope before making changes: "I'll modify X. Should I also update Y?"
- Make minimal, targeted edits for bug fixes - don't refactor adjacent code
- Stop after completing the stated task - don't continue to "improve" things
- Ask before expanding scope: "I noticed Z could also be improved. Want me to address it?"
**Never:**
- Make changes beyond the explicitly requested scope
- Refactor working code while fixing a bug
- Add "improvements" that weren't requested
- Continue with tangential work after completing the main task
#### Session Management
- Provide checkpoint summaries every 3-5 edits on complex tasks
- Before session timeout risk, summarize progress and provide continuation notes
- Prioritize delivering a working solution over exploring alternatives
- If time is short, deliver partial working solution rather than incomplete exploration
- Don't get stuck in exploration mode - propose a concrete fix
**Prefer:**
- When editing multiple similar files, prefer sequential edits over parallel to avoid 'file modified since read' conflicts
#### Multi-Agent Coordination
- When spawned as a subagent, focus exclusively on the delegated task
- Don't spawn additional subagents without explicit permission
- Report completion status clearly: "Task complete. Ready for next instruction."
- Acknowledge and dismiss stale notifications rather than context-switching
- Maintain focus on parent agent's primary request
#### Autonomous Iteration
- For test failures: run tests -> analyze -> fix -> re-run (up to 5 cycles)
- For type errors: run tsc --noEmit -> fix -> re-run until clean
- For lint errors: run linter -> fix -> re-run until clean
- Report back only when: task complete, or stuck after N attempts
- Document iteration attempts for debugging
#### Testing Integration
- After any code change, run the relevant test file if it exists
- For TypeScript files, run tsc --noEmit to catch type errors
- Validate changes work before marking task complete
- Mock stdin/stdout for interactive prompt tests in CLI tools
### Agent-Specific Learnings
- [Include learnings from central file for this specific agent]
- [If no agent-specific learnings exist, write: "No agent-specific learnings yet."]Agent Files to Update
Process these files in order (sequentially, not in parallel):
devops-aws-senior-engineer.mddevops-docker-senior-engineer.mdexpo-react-native-engineer.mdexpress-senior-engineer.mdfastapi-senior-engineer.mdlaravel-senior-engineer.mdnextjs-senior-engineer.mdnodejs-cli-senior-engineer.mdpython-senior-engineer.md
Agent-Specific Learnings Reference
Copy these from the central learnings file:
| Agent | Specific Learnings |
| nodejs-cli-senior-engineer | Test --help output after commander.js changes; Validate exit codes; Use Pino logger |
| TypeScript agents (nextjs, express, expo) | Run tsc --noEmit after edits; Prefer explicit types; Use strict mode |
| DevOps agents (aws, docker) | Validate with dry-run; Document resource changes; Test locally first |
| python-senior-engineer | No agent-specific learnings yet |
| laravel-senior-engineer | No agent-specific learnings yet |
| fastapi-senior-engineer | No agent-specific learnings yet |
Phase 5: Verification
Gate: All checks pass before marking complete.
Step 5.1: Verify Learnings Section Exists
Run this command to verify ALL agent files have the ## Learnings section:
grep -l "^## Learnings" .claude/agents/*.md | wc -lExpected result: 9 (one for each agent file)
If the count is less than 9, identify which files are missing and fix them.
Step 5.2: Verify Section Content
For each agent file, verify the Learnings section contains:
### Global Learningsheader#### Scope Controlsubsection#### Session Managementsubsection#### Multi-Agent Coordinationsubsection#### Autonomous Iterationsubsection#### Testing Integrationsubsection### Agent-Specific Learningsheader
Step 5.3: Display Summary
Learnings Update Complete
**Central Learnings File:**
- Added X global learning(s)
- Added Y agent-specific learning(s)
**Agent Files Updated:**
- [agent-name.md]: ✓ Learnings section verified
- [agent-name.md]: ✓ Learnings section verified
[...for each agent...]
**Verification Results:**
- grep "^## Learnings" count: 9/9 ✓
- Central file structure valid ✓
- All agent files have complete Learnings section ✓Quality Checklist
Before marking the update complete, verify:
- Learnings are actionable (not vague observations)
- Learnings use imperative mood ("Do X" not "Should do X")
- Category assignment is appropriate
- Global vs agent-specific classification is correct
- No duplicate learnings added
- Central file structure is preserved
- CRITICAL: Run
grep "^## Learnings" .claude/agents/*.mdto verify ALL agent files have the## Learningssection - Each agent's Learnings section contains ALL global learning categories (Scope Control, Session Management, Multi-Agent Coordination, Autonomous Iteration, Testing Integration)
- Agent-specific learnings are included where applicable
Examples
Example 1: Adding a Global Scope Control Learning
Session Issue: Agent modified test files when only asked to fix production code.
Learning Extraction:
- Category: Scope Control
- Scope: Global
- Action Type: Never
- Learning: "Never modify test files unless explicitly requested, even if tests are failing due to production changes"
Result:
- Added to
.claude/learnings/agent-learnings.mdunder Global Learnings → Scope Control - Synced to all 8 agent files under their
## Learningssection
Example 2: Adding an Agent-Specific Learning
Session Issue: Node.js CLI agent used console.log instead of Pino logger.
Learning Extraction:
- Category: Testing Integration
- Scope: nodejs-cli-senior-engineer
- Action Type: Always
- Learning: "Always verify Pino logger is used instead of console.log when reviewing CLI code changes"
Result:
- Added to
.claude/learnings/agent-learnings.mdunder Agent-Specific Learnings → nodejs-cli-senior-engineer - Added only to
nodejs-cli-senior-engineer.mdunder Agent-Specific Learnings
Example 3: Adding a Claude Code Only Learning (NOT propagated to subagents)
Session Issue: Improved a skill without first reading a reference skill for quality patterns.
Learning Extraction:
- Category: Skills & Configuration
- Scope: Claude Code Only
- Action Type: Always
- Learning: "When improving a skill or configuration file, read a reference example first to understand the quality bar and structural patterns expected"
Result:
- Added to
.claude/learnings/agent-learnings.mdunder Claude Code Only Learnings → Skills & Configuration - NOT propagated to any subagent files (nodejs-cli, fastapi, etc. don't create skills)
Why Claude Code Only? This learning is about meta-work (improving skills/configs) that only the main Claude Code agent does. The specialized engineer agents (nodejs-cli-senior-engineer, fastapi-senior-engineer, etc.) focus on writing application code, not on creating or improving Claude Code skills.
Integration with Other Skills
This skill works well after:
commit— After committing, reflect on what went wrong during the sessioncreate-pr— After PR creation, capture learnings about the implementation processstart— At session start, review existing learnings
Safety Rules
| Rule | Reason |
| Always get user confirmation before writing | Ensures learnings are accurate and desired |
| Never delete existing learnings | Preserve institutional knowledge |
| Preserve file structure when editing | Maintains compatibility with other tools |
| Keep learnings concise and actionable | Prevents bloat and ensures usability |
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.

