| name | learn |
| description | Codify a correction or convention from the current session into AGENTS.md (global) or .agents/conventions.md (project-specific) in "Always/Never [action] BECAUSE [reason]" format. Use this skill whenever the user says "remember this", "add a rule", "don't do that again", "learn this", "/learn", or wants to capture a lesson from the session before the conversation ends. Entry point: /learn [optional rule text]
|
Learn Skill
Captures a rule or correction from the current session and writes it to a durable
location in "Always/Never [action] BECAUSE [reason]" format — before the conversation
ends and the lesson is lost.
Two destinations:
AGENTS.md — global rules that apply in all projects.agents/conventions.md — project-specific patterns for this repo only
Proactive Triggers
In addition to explicit /learn invocations, auto-write a rule when you detect these patterns:
- User corrects the agent's approach ("no", "wrong", "actually", "that's not right", "don't do that", "I meant", "stop")
- User uses prescriptive language ("always X", "never Y", "make sure to", "we should")
- User expresses frustration about a repeated mistake or pattern
- User provides a corrected command, syntax, or workflow after the agent made an error
When one of these triggers fires, write the rule immediately — do not ask for confirmation.
The user can always revert via git (both AGENTS.md and .agents/conventions.md are tracked).
Gotchas
- If the user invokes
/learn <rule text>, skip Step 1 and use that text directly.
- Choose "Always" for positive behaviors, "Never" for prohibitions — match how the rule is naturally expressed.
- The
## Always / Never section must be a top-level heading. If it doesn't exist, append it at the end of the file — never insert it mid-document.
- A rule without a BECAUSE clause is a bare directive. Bare directives lose their meaning out of context and get ignored over time. Always get the reason.
Step 1: Capture the Rule
If the user provided rule text inline with the slash command, use it directly and skip
to Step 2.
Otherwise ask:
"What's the rule you want to capture? (e.g. 'never use bare except clauses' or
'always validate input before calling external APIs')"
Step 2: Get the "Why"
If the text does not include a causal phrase ("because", "so that", "since", or similar),
ask for the reason:
"Why should this rule exist? This becomes the BECAUSE clause — the reason is what makes
the rule durable and applicable to new situations."
Format the final rule:
Always [action] BECAUSE [reason]Never [action] BECAUSE [reason]
Step 3: Check for Duplicates (Auto-Merge)
Extract the 2–3 most distinctive terms from the rule and search both target files:
grep -i "[key term 1]" AGENTS.md .agents/conventions.md 2>/dev/null
If a similar rule is found, auto-merge: replace the existing rule with the new one.
The new text takes precedence — it reflects the latest correction.
If no similar rule, proceed to Step 4.
Step 4: Determine Scope
Ask:
"Is this rule global (applies in all projects → AGENTS.md) or project-specific
(only for this repo → .agents/conventions.md)?"
...
- Global →
AGENTS.md in the project root
- Project-specific →
.agents/conventions.md (create if it doesn't exist)
Step 5: Write the Rule
Check whether the target file has an ## Always / Never section:
grep -n "^## Always" AGENTS.md 2>/dev/null
If the section exists: Read the file, find the ## Always / Never heading, and
append - [formatted rule] as the next bullet point under it (before the next ##
heading or EOF). Write the file back.
If the section does not exist: Append the following block to the end of the file:
## Always / Never
- [formatted rule]
Use read → modify in memory → write back. Do not use sed with complex in-place edits.
Step 6: Confirm
Show what was written:
Rule captured:
File: AGENTS.md (or .agents/conventions.md)
Rule: Never use bare except clauses BECAUSE they silently swallow all errors,
making debugging impossible and hiding production failures.
