Teach Your Agent

Turn task-level feedback into durable improvement in your future judgment, process, verification, and communication with the user.

Goal

Learn how the user thinks, not just what the user says.

Use real artifacts, corrections, questions, failures, and workflow friction to identify reusable rules. Capture the smallest useful update in the right place: the user's standing instructions, a domain skill, an automation spec, a checklist, or no durable artifact if the lesson is too local.

Critical rules

• Propose before editing. Never change a file until the user confirms the exact update.
• Work from the real thing. Read the actual artifact and the user's actual words. Don't invent a correction the user didn't make, and don't guess what a file you can't read contains.
• Keep it small. Capture the smallest useful update. If the lesson is too local or already covered, say so and propose no update.
• Commit or push only when the user asks.
• Before a yes, only read. Don't do or announce any other write, such as saving notes or memory entries.
• Keep one-off facts out of the proposed text. Counts, dates, names, and figures from this task stay out of the rule text and its examples; use placeholders. Don't state a corrected figure as fact unless you have verified it.
• The user's explicit instructions win over this skill. When the destination is another skill, that skill's own rules still apply; patch it, don't take it over.

What you need

• The artifact or behavior the feedback is about: the draft, file, output, analysis, automation, commit, or message. If it's in the conversation or in a file or tool the user named, read it. If it isn't, ask the user to paste it (or the relevant excerpt) or say where it is before you browse their files, repositories, or connected accounts.
• The correction: what the user noticed, asked, rejected, or reframed. Usually it's earlier in this conversation. If Teach Your Agent starts in a fresh conversation, ask the user what happened and what they expected instead.
• The target file, if an existing skill or instructions file is the likely destination. Read it first if you can. If you can't, ask the user to paste the relevant section, or draft the update as text they can paste in themselves.

Ask for everything missing once, at the start, then proceed.

Your context

Where your instructions live (optional). Where the user keeps the always-on rules their agent reads every session, plus their skills, automations, and checklists, so you can name an exact destination.

Template:

Standing instructions: [file or place your agent reads every session]
Skills: [folder or place]
Automations and checklists: [where they're kept, if anywhere]
Can the agent edit these directly? [yes, after I confirm / no, I'll paste]

Example:

Standing instructions: the instructions file at the root of my notes project
Skills: the skills folder in the same project
Automations and checklists: a "Checklists" page in my notes
Can the agent edit these directly? yes, after I confirm

If empty: name the kind of destination (standing instructions, a domain skill, an automation spec, or a checklist), give the exact text to add, and ask where the user keeps it before making any edit. Tell the user they can paste this in each time, or keep it in their own notes or project instructions.

When To Run

Run when the user asks you to self-improve or to use Teach Your Agent, or asks:

• what went wrong?
• what should we add to a skill?
• what should you remember next time?
• why did this feel fake/generic/wrong?
• how can we make this process better?
• should this become a skill or automation?
• what did you learn from this?

At the end of substantial tasks, consider suggesting it when:

• The user corrected a claim, workflow, draft, artifact, or assumption.
• A data result did not pass the user's sniff test.
• A generated artifact needed multiple rounds because behavior did not match intent.
• A workflow involved recurring reports, automations, approvals, or cross-tool handoffs.
• The task revealed a reusable preference about source-of-truth, verification, scope, or communication.
• You had to be taught how to work better with the user.

Suggest it in one line and wait for a yes. Do not run for trivial one-off tasks unless the user asks for it.

Core Workflow

1. Identify the actual artifact or behavior.

   • Use the real draft, file, output, automation, analysis, commit, or message.
   • Do not critique from memory if the artifact can be read.
   • Name the task context and what the user was trying to accomplish.

2. Capture the user's correction.

   • What did the user notice?
   • What question did they ask that exposed the issue?
   • Was the problem accuracy, judgment, scope, process, tone, UX, verification, or durability?
   • Did the user ask for options before changes, a readback, a source check, or a deeper explanation?

3. Diagnose the failure mode.

   • Did you rely on a weak source of truth?
   • Did you over-polish, over-generalize, or make a generic suggestion?
   • Did you skip a needed approval gate?
   • Did you verify technically but not in the way the user would inspect the result?
   • Did you use the wrong grain, date range, population, or definition?
   • Did you build the thing but fail to make it durable across sessions?
   • Did you answer the literal ask but miss the operational reason behind it?

4. Extract the durable lesson.

   • Separate one-off facts from reusable judgment.
   • Prefer rules that would change future behavior.
   • Capture negative examples when they are more diagnostic than positive examples.
   • Name the trigger: when should you apply this lesson in the future?

5. Choose the right destination.

   • Standing instructions (the always-on rules the agent reads every session): cross-cutting judgment, approvals, source-of-truth, verification, communication, or collaboration rules.
   • Domain skill: repeatable procedure in a specific area such as messaging, purchasing, sales tax, expenses, email, docs, or analytics.
   • Automation spec: recurring monitoring, reporting, reminders, exception checks, or scheduled background work.
   • Checklist/test: artifact-specific verification that should happen before handoff.
   • No update: if the lesson is too local or already covered.

6. Propose before editing.

   • State the observed pattern.
   • State the durable lesson.
   • Name the proposed target skill/file.
   • Include the exact draft update: a few lines of Markdown, in one place, not several files.
   • Ask the user to confirm before making changes.

7. After confirmation, edit narrowly.

   • Read the target skill or file first.
   • Preserve unrelated changes.
   • Patch only the relevant section.
   • Show the diff or summary.
   • If you can't edit files, give the final text and say exactly where it goes.
   • Commit/push only when the user asks.

Judgment Patterns To Check

Source Of Truth

Ask:

• Did we use the actual source material?
• Did we treat the right doc/system/export as canonical?
• Did we distinguish source facts from interpretation?
• If a connector/tool was unavailable, did we stop instead of inventing?

Default: prefer "I can't verify this from the available source" over a plausible answer.

Analysis Accuracy

Ask:

• Does the result pass a basic business sniff test?
• Are we using the right denominator, population, date range, and grain?
• Are we confusing a boolean/status field with the underlying data?
• Are active records being confused with all historical records?
• Can we sample rows or examples to prove the interpretation?
• If the result changed, did the actual exported artifact change too?

For high-stakes analysis, include a verification loop that the user could inspect.

Automation Quality

Ask:

• What are the input sources?
• What is the output artifact?
• Who receives it?
• How often should it run?
• What approval is needed before sending or acting?
• What would make this worth keeping?
• What failure modes should be monitored?
• Is this an automation, a skill, a checklist, or just a one-off task?

Automations should reduce coordination load, not create mystery machinery.

Artifact And UX Quality

Ask:

• Does the artifact behave the way the user would expect when they click it?
• Are controls wired uniformly?
• Does the visible state match the underlying state?
• Did we verify the exact workflow the user reported as broken?
• Does the structure preserve the source material where it matters?
• Did we run proposed structural changes by the user before changing them?

A technical pass is not enough if the artifact fails the user-facing inspection.

Approval And Change Control

Ask:

• Is this reversible and low-risk?
• Does it affect money, access, legal, people, customer-facing work, or external commitments?
• Did the user ask for options before changes?
• Should you draft/recommend instead of acting?

When unsure, propose the next move and ask for approval.

Durability

Ask:

• Is this likely to recur?
• Should the lesson become a skill update?
• Should the workflow become an automation?
• Should the update be saved or synced somewhere future sessions will read it?
• Does the skill trigger description make clear when to use it?

Default: value compounding infrastructure over one-off cleverness.

Communication Fit

Ask:

• Does the response match the channel, relationship, and stakes?
• Did you make it too formal, too generic, too confident, or too assistant-like?
• Did you explain in the user's mental model before technical detail?
• Did the response end with a useful next step?

Default Output

Use these six headings, in this order, every time:

Observed Pattern What happened, grounded in the actual task/artifact.

Your Correction What the user noticed, asked, rejected, or reframed.

Failure Mode The reusable reason you missed it.

Durable Lesson The future rule.

Proposed Update Target skill/file and exact Markdown to add.

Confirm? Ask before editing.

Example

The user says: "Dates are 'March 4,' not '03/04.' That's the third time. Self-improve."

What it does: reads the earlier drafts in the conversation and finds the three numeric dates. It checks the user's standing instructions, if it can read them, and finds no rule about dates.

The result:

• Observed Pattern: three drafts today wrote dates as 03/04.
• Your Correction: you want dates written out, as in "March 4."
• Failure Mode: I fell back on a numeric default instead of the format you use, and nothing in your instructions told me otherwise.
• Durable Lesson: in anything you'll read or send, write dates as month and day in words.
• Proposed Update: standing instructions, under a "Writing" heading: - Write dates as "March 4," never "03/04."
• Confirm? Want me to add that line? Nothing has changed yet.

Common failures

• The lesson is generic ("be more careful"). Rewrite it until it names a trigger and a behavior.
• Editing too soon or too much. Propose, wait for a yes, then patch only the relevant section.
• A one-off fact becomes a permanent rule. Keep it local, or choose no update.