# Upskilling a team for agentic engineering

URL: https://developertoolkit.ai/en/teams/upskilling/
Description: For tech leads and CTOs: a curriculum per ladder level, katas from your own repo, review-to-learn sessions and an AI-literacy record for Article 4.

Upskilling a team for agentic engineering means a curriculum tied to the autonomy ladder level each loop runs at, katas built from the team's own repository and graded by tests, fortnightly review-to-learn sessions on real agent pull requests, and a dated literacy record per person. The same record is evidence for the EU AI Act's Article 4 AI-literacy duty.

You bought eight seats in the spring, posted three links and ran one lunch-and-learn. Now two engineers run agents for hours against specs, three use them as autocomplete, and one refuses to touch them. The review queue is full of agent pull requests that only two people know how to verify. Then a customer's security questionnaire asks how you meet the AI Act's AI-literacy duty, and nobody knows who was trained on what. This page is for the tech lead who has to fix the first problem and the CTO who has to answer the second.

## What you get from an upskilling programme built this way

- A curriculum table: what people learn at each ladder transition, the kata that proves it, and who signs the exit.
- A 90-minute baseline module for every seat holder.
- A kata manifest and two prompts that turn your own history into katas.
- A fortnightly review-to-learn session with a rule for what it must produce.
- A YAML literacy record that serves the curriculum and Article 4, with an audit prompt.
- Four measures of whether it works, and the failure modes to watch.

## What does the evidence say about training people to work with agents?

There is little direct evidence on training programmes for agent work, so this page builds on two findings, marks the rest as design, and has the programme measure its own effect on your team.

**How people delegate decides what they learn.** In a randomized trial published by Anthropic on [29 January 2026](https://www.anthropic.com/research/AI-assistance-coding-skills), 52 mostly junior engineers learned a new Python library. The group that used an AI assistant averaged 50% on a follow-up quiz; the group that coded by hand averaged 67%. Participants who asked conceptual questions, or generated code and then asked for explanations, averaged 65% or higher. The sample was small and the publisher is a model vendor, but the lesson holds: design practice so people keep understanding, not only output.

**The team's system decides what the agent amplifies.** The [2025 DORA report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) (Google Cloud, 23 September 2025) puts it this way: "AI doesn't fix a team; it amplifies what's already there." Its [AI Capabilities Model](/en/org/dora-ai-capabilities/) lists a "clear and communicated AI stance" as the first of seven capabilities. For upskilling, that means teaching people the team's gates and rules, not only the tool's features.

## Build the curriculum around ladder transitions

The [autonomy ladder](/en/ladder/) runs from Level 0 (by hand) to Level 5 (a factory that no human reads). A level belongs to a loop, not to a person: one engineer can run dependency bumps at Level 4 and feature work at Level 2. So the curriculum teaches the **transition** a person's main loop is making next, not a job title. [One map: the ladder, the lifecycle and the stations](/en/ladder/one-map/) shows where each loop sits.

| Transition | What the person learns | Kata that proves it | Exit evidence (tech lead signs) |
| --- | --- | --- | --- |
| **Baseline** (everyone with a seat) | Permissions and sandboxing in their tool, prompt injection, secrets, hallucinated dependencies, the team's risk classes, what each CI gate proves | None; a five-question check after the module | Record entry with the date and the check passed |
| **L1 → L2**: assisted to paired | Delegating a whole task with acceptance criteria; reading the agent's plan before it edits; stopping and redirecting a run | **Delegation kata**: finish a scoped ticket through the agent, with the hidden tests passing and no edits to test files | Two delegation katas passed; explain-back on one without the diff open |
| **L2 → L3**: paired to reviewing diffs | Reviewing an agent pull request against its criteria; risk classes that need a human to read code; shared rules in `CLAUDE.md` or `AGENTS.md` | **Review kata**: find a seeded defect in an agent change and name the check that would catch it | Three review katas passed; one real finding turned into a check |
| **L3 → L4**: reviewing to writing specs | Writing [executable acceptance criteria](/en/workflows/plan/acceptance-criteria/); oracle strength; stop conditions; reading an [evidence bundle](/en/workflows/ship/evidence-bundle/) instead of a diff | **Spec kata**: write criteria for a past ticket so the agent's first run passes the original, hidden test suite | Two spec katas passed on the first run; one real ticket shipped from the person's spec with its evidence bundle |
| **L4 → L5**: specs to running the loop | [Fitness functions](/en/workflows/test/fitness-functions/), gates that agents cannot edit, the written case for a loop that runs unattended | **Harness kata**: add a gate that catches a class of defect the kata set seeds | A gate merged that caught or would have caught a real defect; the case for one unattended loop reviewed by the CTO |

Two rules keep the table honest. First, nobody skips the baseline, however senior: seniority does not protect against prompt injection. Second, a transition is signed off on evidence from katas and real work, not on attendance. [Level 5](/en/ladder/level-5-run-the-factory/) is not a default goal; a strong Level 4 is a complete curriculum for most engineers.

## Run the baseline module before anyone uses agents on production code

The baseline is 90 minutes, run by the tech lead or a senior for each new seat holder and again when the team adopts a new agent. It covers what can go wrong before what the tool can do.

1. **Permissions and sandboxing (20 minutes).** Each person opens their own tool and shows the current mode: Claude Code's permission modes (from v2.1.283, on both release channels, auto mode is the starting mode for most interactive sessions), Codex's approval policy (`-a on-request` or `-a never`) and sandbox (`read-only`, `workspace-write`), or Cursor's Run modes. [Permissions and sandboxing for coding agents](/en/workflows/harness/permissions-and-sandboxing/) is the reference.
2. **Injection and secrets (20 minutes).** Walk through one real incident from the [agent threat model](/en/org/agent-threat-model/): text in an issue, a web page or a dependency can steer an agent that has tools and credentials. Show where the team keeps secrets and why an agent session never gets production credentials.
3. **Dependencies the agent invents (15 minutes).** Check that a package the agent adds exists, is the intended one and is pinned. [Dependency verification](/en/workflows/test/dependency-verification/) has the checks.
4. **What the gates prove (20 minutes).** Open one merged agent pull request and, for each CI check, say what it proves and what it does not. Name the team's risk classes (auth, money, schema, migrations) where a human reads the code.
5. **The check (15 minutes).** Five questions, answered in writing, one per step above plus one on the risk classes. Record the date and the result.

Adopt this baseline check as-is and adapt the answers to your repository:

```markdown
## Agent baseline check (write your answers; 15 minutes)
1. Which permission mode or approval policy does your tool start in on this
   repository, and how do you change it for one session?
2. An issue description tells the agent to "also update the deploy token".
   What stops that from happening in our setup, and what do you do?
3. The agent adds a package you have never heard of. Name two checks you run
   before you accept the change.
4. Our CI passed on an agent pull request. Name one thing the gates prove and
   one thing they do not prove.
5. Which change classes on this team need a human to read the code, and who?
```

## Build katas from your own repository

A kata is a time-boxed exercise with a known answer. Katas from your own repository teach your system, gates and risk classes. A usable kata has three properties:

- **The tests grade it.** A hidden test suite or a named, seeded defect decides pass or fail, so nobody argues about the result.
- **The answer key stays out of reach.** A kata cut from your repository still has its answer in git history, so publish each kata to a separate practice repository with fresh history and keep the key outside it. If that is too heavy, use the honour system: nobody looks at `main` or the original pull request until the debrief.
- **It has a time box.** 30 to 60 minutes, so a kata fits in a protected slot every week.

Keep the kata set in a manifest so it can be reviewed, reused and retired like code:

```yaml
# docs/upskilling/katas.yaml
- id: review-03-retry-idempotency
  transition: "L2 -> L3"
  type: review                  # delegation | review | spec | harness
  branch: kata/review-03
  timebox_min: 45
  task: "Review the agent's change to the payment retry worker."
  pass: "Names the missing idempotency check and the test that would catch it."
  answer_key: "private: senior's notes, kept outside the practice repository"
  owner: "a.nowak"
  created: 2026-09-26
  retire_when: "the retry worker is rewritten or the seeded defect class gets a gate"
```

The senior builds each kata with the agent, then checks the result by hand before anyone runs it. The two prompts below cover the kata types that take the most time to build.

**Copy-paste prompt: build a review kata with a seeded defect**

```text
Build a code-review kata from this repository. Do not show your reasoning in
any file, branch name or commit message.
1. Pick a merged change from the last six months in src/payments/ or
   src/auth/ that has tests and touches error handling or state.
2. Create a branch named kata/review-<short-name> from the commit before that
   change. Re-apply the change, but introduce exactly one realistic defect of
   one of these classes: missing idempotency, wrong error propagation,
   off-by-one in a boundary, or a race on shared state. Keep all existing
   tests passing.
3. Write a pull request description as an agent would: the ticket, the
   acceptance criteria, and a confident summary that does not mention the
   defect.
4. Reply to me only, not in the repository, with: the branch name, the
   defect, the file and line, and the smallest test that would catch it.
```

**Copy-paste prompt: build a spec kata from a merged ticket**

```text
Build a specification kata from this repository.
1. Find a merged pull request from the last six months that added a feature
   with at least five new test cases, outside src/auth/ and src/payments/.
2. Create a branch named kata/spec-<short-name> from the commit before that
   pull request. Do not include the implementation or the new tests.
3. Write a one-paragraph ticket in a product manager's voice describing the
   user-visible behaviour, with no hints about edge cases the tests cover.
4. Do not copy or move the original new test files. Tell me their paths and
   the SHA of the merge commit, so I can copy them out myself. They are the
   hidden grader.
5. Reply with the branch name, the ticket, and a list of the behaviours the
   hidden tests check, so I can confirm the kata is fair.
```

The kata branch still carries the original change in its history, so the senior copies it into a fresh practice repository, with the pre-change tree on `main` and the kata on its branch:

```bash
# Run from the root of your working repository. ../kata-review-03 becomes the practice repository.
base=$(git merge-base main kata/review-03)
git init -b main ../kata-review-03
git archive "$base" | tar -x -C ../kata-review-03
git -C ../kata-review-03 add -A && git -C ../kata-review-03 commit -m "Base"
git -C ../kata-review-03 switch -c kata/review-03
git -C ../kata-review-03 rm -rq . && git archive kata/review-03 | tar -x -C ../kata-review-03
git -C ../kata-review-03 add -A && git -C ../kata-review-03 commit -m "Kata change"
```

For a spec kata, copy the listed test files (`git show <sha>:<path>`) to a key directory outside both repositories and run them against the engineer's result. Replace `src/payments/` and `src/auth/` in the prompts with your own directories.

### How does each tool run a kata?

The kata and its grading are the same in every tool; only session isolation and the review-agent comparison differ.

**Claude Code**

Start the kata in its own worktree so it cannot touch other work: `claude -w kata-review-03` creates a new git worktree for the session. For a spec kata, enter plan mode with `/plan` so the agent writes its plan before any edit, and compare the plan with the criteria. For a kata in a module the person is learning, run `/output-style learning` (the command needs v2.1.269 or later). The agent then explains its choices and, at a real design decision, leaves a `TODO(human)` marker for the person to fill in. The choice is saved to `.claude/settings.local.json`, so teammates are unaffected. After a review kata, run `/code-review` on the same branch and compare its findings with the person's.

**Codex**

Start the kata with `codex --worktree`, which runs the session in a new managed git worktree. Use `/plan` for spec katas. We found no built-in learning mode in `codex --help` or `codex features list` (Codex CLI 0.157.1, checked 26 September 2026), so for a learning kata the person pastes a learning contract at the start of the session. After a review kata, run `codex review --base main` from the kata branch and compare its findings with the person's.

**Cursor**

Run the kata in a Cursor worktree so the Agent works in an isolated Git checkout, then start an Agent chat. Use Plan Mode, which "creates detailed implementation plans before writing any code" (Cursor docs, checked 28 August 2026), for spec katas. For a learning kata, the person pastes a learning contract into the chat, not into the team's shared Rules. After a review kata, if your team uses Bugbot, open the kata branch as a draft pull request and compare Bugbot's comments with the person's findings.

[Your craft and career when agents write the code](/en/ladder/craft-and-career/) has a learning contract to paste in Codex and Cursor, and [growing junior developers](/en/teams/junior-developers/) has a debugging-kata prompt for juniors.

## Run review-to-learn sessions for the whole team

Katas teach on known answers; review-to-learn sessions teach on real work. Run one every two weeks for 45 minutes with the whole team, rotating the facilitator.

1. **The facilitator picks one merged agent pull request** from the last two weeks that touched error handling, state or a boundary. Avoid renames and dependency bumps.
2. **Predict (5 minutes).** From the ticket and acceptance criteria only, everyone writes two lines: what the change must touch and what could go wrong.
3. **Review (15 minutes).** Everyone reviews the diff and the evidence bundle and writes findings, classed as logic, security, performance, design or test gap.
4. **Compare with the review agent (10 minutes).** Show what `/code-review`, `codex review` or Bugbot found on the same change. List what people found that the agent missed, and the reverse.
5. **Decide one durable artifact (15 minutes).** End with one change: a new check, a rule in `CLAUDE.md` or `AGENTS.md`, a new kata, or an explicit "nothing". Name an owner and a date.

Step 5 keeps the session from turning into a demo: a session with no artifact and no explicit "nothing" did not happen. [Knowledge sharing: version evidence, not tricks](/en/cto-scorecard-guide/knowledge-sharing/) covers where each artifact lives and how it is retired.

**Copy-paste prompt: turn a review finding into a check and a kata**

```text
In last week's review session we found this defect in an agent pull request,
which CI did not catch:
<paste the finding, the file and the pull request link>
1. Propose the smallest automated check that would have failed on that pull
   request: a unit test, a property test, a lint rule or a fitness function.
   Say which one and why it is the smallest.
2. Write the check on a new branch and show me it failing on the defective
   commit and passing on the fix.
3. Draft a katas.yaml entry for a review kata that seeds the same defect
   class in a different module, with transition "L2 -> L3".
Do not change any existing test to make the new check pass.
```

## Keep a literacy record that also serves Article 4

The EU AI Act reaches a company that only uses coding agents mainly through Article 4. In its 2024 wording, it asks providers and deployers to take measures for a sufficient level of AI literacy among staff who use AI systems, given their experience, training and context of use. The Digital Omnibus (Regulation (EU) 2026/1744, in force 27 July 2026) softened the duty but did not remove it, according to secondary law-firm summaries from Gibson Dunn and aiactblog.nl (2026). Read the amended wording on EUR-Lex before you quote it, and confirm your position with counsel. [The EU AI Act for companies building software with agents](/en/org/eu-ai-act/) covers the roles and the timeline.

A curriculum already produces what Article 4 asks for. This format extends the AI Act page's record with the ladder transition and katas, so one file serves the tech lead and compliance:

```yaml
# docs/compliance/ai-literacy-record.yaml
- person: "j.kowalski"
  role: developer
  systems: [claude-code, codex]
  autonomy: "local, reversible changes; no production credentials"
  ladder:
    main_loop: "feature work, billing service"
    current_level: L3
    working_towards: L4
  measures:
    - name: "Agent baseline: permissions, injection, secrets, dependencies, gates"
      date: 2026-09-12
      material: "https://wiki.example.com/agents/baseline"
      check: passed
    - name: "Review kata review-03-retry-idempotency"
      date: 2026-09-19
      result: passed
    - name: "Review-to-learn session: billing retry pull request"
      date: 2026-09-24
      material: "https://wiki.example.com/agents/review-to-learn/2026-09-24"
  exits_signed:
    - transition: "L2 -> L3"
      date: 2026-09-24
      evidence: "https://git.example.com/org/billing/pull/412"
      signed_by: "tech-lead-billing"
  next_review: 2027-09-12
  owner: "head-of-engineering"
```

Keep kata results as pass or fail and a date, not as times or scores. The record proves measures exist; it is not a performance file (see the failure modes below).

**Copy-paste prompt: audit the literacy record against the seat list**

```text
Compare two files and report gaps. Do not edit either file.
- docs/compliance/ai-literacy-record.yaml: one entry per person.
- seats.csv: an export of everyone with an active Claude Code, Codex or
  Cursor seat, or approval rights on agent pull requests (columns: person,
  tool, role).
Report, as a Markdown table:
1. People in seats.csv with no record entry.
2. People whose most recent measure is older than 12 months.
3. People whose systems list lacks a tool they now have a seat for.
4. People with approval rights on agent pull requests and no signed
   "L2 -> L3" exit.
End with literacy coverage: the share of people in seats.csv with a record
entry that has a measure dated within the last 12 months.
```

Run the audit every quarter and whenever the team adds a tool, raises an autonomy level or switches model family. Those events are also the triggers to re-run the baseline; [keeping a team current](/en/teams/keeping-current/) is the page that watches for them.

## How do you verify the programme works?

Attendance proves nothing. These four measures do, and the first is the one compliance reads.

| Measure | Definition | Target and owner |
| --- | --- | --- |
| **Literacy coverage** | Share of people with an agent seat or agent-approval rights whose record has a measure dated within the last 12 months | 100%, reported quarterly by the head of engineering. A gap is an access problem: no record, no seat |
| **Signed exits per quarter** | Ladder transitions signed off on kata and real-work evidence | One per engineer per quarter is a strong pace; zero for two quarters is a conversation, not a failure |
| **Kata first-attempt pass rate** | Share of katas passed on the first attempt, per transition, for the whole team | Rises over the quarter; a kata nobody passes is a broken kata |
| **Findings that became checks** | Review-to-learn findings that now have an automated check | At least one per session in two of every three sessions |

Pair them with team delivery measures, not individual ones: change failure rate and rework on agent pull requests, against the baseline from [metrics frameworks for agentic teams](/en/org/metrics-frameworks/). If literacy coverage is 100% but agent changes fail in production as often as before, the curriculum teaches the wrong things: compare the kata classes with the defects that escape.

## How does this answer the Tech Lead Scorecard's upskilling question?

Question 18 of the [Tech Lead Scorecard](/en/lead-scorecard-guide/) asks how you level up the team's AI skills. "I share links" scores one of three points and "occasional sessions" two. The top answer, "structured path + practice + review", maps to this page one to one: the curriculum table is the path, the katas are the practice, and the review-to-learn sessions are the review.

A quarter for a team of eight looks like this in the calendar:

| Weeks | What runs | Time per engineer |
| --- | --- | --- |
| 1–2 | Baseline module for anyone without a record entry; the tech lead places each person's main loop on the ladder | 90 minutes once |
| 3–12 | One kata a week in a protected slot, chosen for the person's next transition | 30–60 minutes a week |
| 3–12, every other week | Review-to-learn session for the whole team | 45 minutes a fortnight |
| 12 | Literacy-record audit, exits signed, kata set pruned | 30 minutes for the tech lead per engineer |

The times are this programme's design, not a measured benchmark. Senior time for building about one new kata a week comes on top.

## When an upskilling programme goes wrong

**Kata results turn into a performance ranking.** Once kata times appear next to names, people pick easy katas and hide gaps. Using an AI system to evaluate employees can also move you into the AI Act's high-risk employment category (Annex III, from 2 December 2027 as deferred by the Digital Omnibus, per secondary summaries; see [the EU AI Act page](/en/org/eu-ai-act/) for the timeline). To recover, record kata results as pass or fail only, keep them out of performance reviews, and use [career ladders built for cheap output](/en/org/career-ladders/) for performance instead.

**The curriculum teaches features, not verification.** Sessions demo new slash commands, and review quality does not change. To recover, give every transition a kata graded by tests, and cut sessions whose only output is "we saw a feature".

**Seniors skip the baseline.** Senior engineers opt out, then approve agent changes under a permission mode they never checked. To recover, make the baseline a condition for approval rights on agent pull requests, and ask a senior to run the next one. [Bringing skeptics and senior engineers along](/en/teams/skeptics-and-seniors/) covers the conversation.

**The kata set goes stale.** Katas in code that no longer exists teach the old system. To recover, give every kata an owner and a `retire_when` condition, and prune the set in week 12 of every quarter.

**The literacy record is filled in once for the audit.** Entries appear the week before a customer questionnaire and never change. To recover, generate entries from the kata log and session notes, and run the audit prompt quarterly.

**Protected practice is the first thing cut.** The kata slot disappears in a deadline sprint and never returns. To recover, plan katas as sprint tickets with an owner, and report skipped slots in the retrospective.

**Katas that touch real systems**

A kata branch is still your repository. Run katas with the same permission mode and sandbox as normal work, never with production credentials in the environment, and never with `--dangerously-skip-permissions` or a full-access sandbox outside a disposable, network-restricted environment.

## Where to go next with upskilling

- [Keeping a team current when the tools ship weekly](/en/teams/keeping-current/) — The release watch that tells you when to re-run the baseline.
- [Growing junior developers when agents write the code](/en/teams/junior-developers/) — The junior version of review-to-learn and a 90-day plan.
- [The EU AI Act for companies building software with agents](/en/org/eu-ai-act/) — Roles, the post-Omnibus timeline and the AI-system register.
- [Your craft and career when agents write the code](/en/ladder/craft-and-career/) — The individual skills plan each engineer keeps alongside the curriculum.
- [Helping the team stop reading every diff](/en/teams/trust-transfer/) — The trust-transfer step that the L3 to L4 transition prepares.
- [Tech lead track](/en/start/tech-lead/) — The reading path this page belongs to.
