Teaching Agents to Learn from Your Team

1. The knowledge problem every team hits

A new agent deployment starts well. The team writes a system prompt, ships it, and agents handle tasks competently. Then the real work begins: someone notices the agent keeps structuring reports the wrong way. Another person discovers it misses security checks that every human reviewer does automatically. A third discovers it doesn’t know the company’s API versioning convention.

Each of these is the same underlying problem: the agent doesn’t know what your team knows.

The model brings enormous general capability, but it knows nothing about your code review standards, your brand voice, your incident response checklist, or the one gotcha in your payment library that burned you last year. Every time a new agent session starts, that institutional knowledge has to be re-explained — or worse, silently assumed and silently violated.

The talk frames this as a knowledge transfer problem, not a model quality problem. The model is not the bottleneck. The bottleneck is the pipeline from your team’s heads into the agent’s context.

There are three mechanisms for that pipeline, each suited to a different kind of knowledge:

Understanding which layer to use — and how to keep each layer sharp — is the core skill this lesson covers.

2. CLAUDE.md: the agent’s standing orders

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every session. Think of it as the agent’s standing orders: things that are always true, always relevant, always must be respected.

Good candidates for CLAUDE.md:

• Build and test commands (npm run build, python3 -m pytest)
• Code style and formatter preferences
• Architectural constraints (“never import from lib/internal in user-facing code”)
• Third-party API usage notes (“our Stripe integration uses API version 2024-06-20”)
• The “don’t touch” list (“do not modify db/migrations/ without a migration ticket”)

Three scope levels let you tune who sees what:

~/.claude/CLAUDE.md          # global — your personal rules across all projects
project-root/CLAUDE.md       # team-shared — checked into the repo, every contributor gets it
project-root/CLAUDE.local.md # personal local override — gitignored, not shared

The most powerful habit around CLAUDE.md is using it as a living document. Whenever a session teaches you something worth keeping, save it immediately. In Claude Code, prefix any message with # and the content gets appended to the appropriate memory file without interrupting your flow:

# always use the transactions helper in db/helpers.ts, never raw prisma.$transaction

Done. That lesson is now encoded and will load in every future session.

The three-level hierarchy means a team can ship a shared CLAUDE.md with project-wide rules while individual developers maintain personal overrides. New team members clone the repo and immediately get every convention the team has encoded — no onboarding document needed.

3. Skills: specialist knowledge on demand

CLAUDE.md handles universal rules well, but many workflows are specialist: they’re only relevant for specific tasks, they need detailed step-by-step instructions, and loading them into every session would waste context on 90% of interactions.

That’s the job for Skills — packages of specialist expertise that activate only when needed.

Anatomy of a skill

A skill is a folder inside .claude/skills/ with a single required file:

.claude/skills/
  code-review/
    SKILL.md           # required: metadata + instructions
    references/        # optional: supplementary docs
    scripts/           # optional: executable helpers
    assets/            # optional: templates, examples

The SKILL.md file follows a two-part structure:

---
name: code-review
description: >
  Perform a code review on a diff, PR URL, or set of files.
  Checks security (OWASP top 10, injection, auth), performance
  (N+1 queries, memory leaks), and correctness (edge cases,
  error handling). Posts structured feedback.
---

## When to use this skill
- User pastes a diff or PR link and asks for review
- User says "review this code" or "check my PR"

## When NOT to use this skill
- General questions about code style not tied to a specific diff
- Refactoring requests (use the refactor skill instead)

## Steps
1. Read the diff or fetch the PR...
2. Check against the security checklist in references/security.md...

Progressive disclosure keeps skills efficient

A naive approach would cram everything into one giant SKILL.md. The Skills framework solves the context budget problem differently with progressive disclosure:

• Discovery tier: Claude reads only the name and description (~100 tokens per skill). This happens at startup for every installed skill.
• Activation tier: When a user request semantically matches a skill’s description, the full SKILL.md body loads (~1,000–5,000 tokens).
• Execution tier: Supporting files in references/ or scripts/ load only when the skill instructions explicitly reference them.

This means you can install 30 skills without noticeably consuming your context window. The cost compounds only when a skill is actually used.

The trigger description is the most important line

Skills activate based on semantic matching between the user’s request and the skill’s description field. A vague description produces a skill that rarely fires. A precise description fires exactly when it should and stays quiet otherwise.

Write five prompts that should activate the skill and three that should not, then test them in fresh sessions. If the skill misses on the activation prompts, the description is too narrow. If it fires on the rejection prompts, the description is too broad.

4. Instructions as code

The single most important cultural shift the talk advocates is treating skill instructions the same way you treat code: version them, review them, and merge them through pull requests.

This shift matters for three reasons:

Accountability. When a skill produces wrong results, you want to know who changed what and when. A git blame on a SKILL.md file answers that question immediately.

Shared ownership. A skill that lives in a private note, a Slack message, or one person’s head is a single point of failure. A skill checked into the team repo belongs to everyone. New joiners get it automatically. Departing colleagues leave it behind.

Continuous improvement. The PR process creates a structured moment to ask: is this instruction right? Does this step still reflect how we work? Should this rule exist at all? Code review on instructions surfaces errors that would otherwise silently degrade agent output for months.

The practical workflow:

1. When you notice an agent doing something wrong — or something right that isn’t encoded — draft the fix as a diff to the relevant SKILL.md or CLAUDE.md.
2. Open a PR with a description explaining what the agent was doing and why this instruction changes that.
3. A teammate reviews it the same way they’d review code: does this match our actual practice? Are there edge cases this misses? Does it conflict with existing instructions?
4. Merge and the improvement propagates to every agent session that uses that skill.

This is not a high-ceremony process. Many skill PRs are two or three lines. The value is in the habit, not the formality.

5. Closing the loop with Dreaming

The workflows above are human-driven: a person notices a problem, encodes a fix, and merges it. That’s necessary and valuable — but it only captures what humans explicitly notice and choose to act on.

Dreaming is Anthropic’s answer to the question: what about the patterns nobody spotted yet?

Dreaming is a scheduled background process that reviews batches of prior agent sessions, extracts patterns across them, and produces a curated memory update. It surfaces things that are invisible at the single-session level: recurring mistakes, workflows that multiple agents converge on independently, preferences shared consistently across a team’s sessions.

How dreaming works

The process runs in four stages:

1. Session logging. Every agent interaction generates a record: inputs, outputs, tool calls, reasoning steps, outcomes. These accumulate in a retrievable store.

2. Pattern extraction. The dreaming process performs meta-reasoning across a batch of logs. It asks: what request types recur? Which approaches succeed? Which fail? Where do agents repeatedly ask for clarification that shouldn’t be needed?

3. Memory consolidation. Extracted patterns become structured memory: refined decision rules, knowledge snippets, flagged failure patterns. The noisy raw logs compress into high-signal guidance.

4. Human review gate. The consolidated memory update is presented to the team before deployment. Teams can accept it automatically, modify specific entries, or reject changes that don’t reflect their actual preferences.

The result: agents in the next session arrive better equipped than agents in the current session, without any explicit human instruction.

Dreaming in multi-agent systems

The pattern becomes more powerful when multiple specialist agents work in parallel. Each agent develops task-specific expertise. The dreaming process reads across all of them and identifies system-wide patterns — not just “this particular code reviewer struggles with auth edge cases” but “every agent that handles Stripe webhooks makes the same three mistakes.”

That cross-agent insight can then propagate as a shared skill update, fixing the problem for every agent in the system at once.

Real-world results

Harvey, a legal AI company, reported roughly a 6x improvement in task completion rates after implementing dreaming. The gain came not from a better model but from a better feedback loop between agent sessions and the knowledge layer those agents draw on.

6. Scaling team knowledge across an organisation

Individual productivity gains from Skills and CLAUDE.md compound as the team grows — if the knowledge distribution system is set up correctly.

Three distribution tiers

Project-level skills (.claude/skills/ in the repo): Skills committed to the repository are version-controlled and automatically available to everyone who clones the repo. A new hire on day one gets the same code review skill, the same API convention guidance, the same incident response checklist that a five-year veteran has. No onboarding document can substitute for this.

Plugins (cross-repo bundles): When a skill is useful across multiple repositories — say, a brand voice skill for a marketing team or a security audit skill for a platform team — it can be packaged as a plugin with optional subagents, MCP configurations, and hooks. Plugins distribute across repos without duplicating the source.

Managed platforms (centralised push): Enterprise deployments can push skill updates to all team members simultaneously. When security discovers a new vulnerability pattern, the detection skill can be updated centrally and propagate to every agent across the organisation within minutes of the PR merging.

The compounding loop

The long-term return on investing in this system is non-linear. A skill that one developer writes improves their own sessions. When that skill is committed to the repo, it improves at team velocity — everyone who encounters an edge case can open a PR to refine it. When dreaming is added to the system, improvements compound automatically between sessions.

The analogy the talk uses is instructive: the team’s knowledge becomes an asset that accumulates over time, rather than tacit expertise that walks out the door whenever someone leaves or gets lost whenever someone forgets to mention a convention in a prompt.

/init

# when running tests, always use `npm test -- --run` (not the watch mode default)

mkdir -p .claude/skills/code-review

---
name: code-review
description: >
  Review a code diff, pull request, or set of files for security,
  correctness, and adherence to team conventions. Posts structured
  feedback by category.
---

## When to use this skill
- User provides a diff, PR URL, or asks to review specific files
- User says "review this", "check my PR", "audit these changes"

## When NOT to use this skill
- Style questions without a specific diff to review
- General refactoring advice without a target

## Review checklist
1. Security: check for injection, auth gaps, secrets in code
2. Correctness: edge cases, error handling, null checks
3. Conventions: follows our naming rules, import structure, commit style
4. Tests: coverage for the changed logic

Structure feedback as: **[Category]** — description — suggested fix.

Can you review the changes I just staged?

How should I generally approach naming variables?

git add .claude/skills/code-review/
git commit -m "feat(skills): add code-review skill with security and correctness checklist"