Capstone 8B — Legacy Migration Agent, Skills-First

Project Brief

You already built this system. Meridian Public Records, eleven Secretary of State offices, 6 TB of UCCUniform Commercial Code — the body of US law governing secured transactions. A UCC-1 financing statement is the public filing a lender makes to claim an interest in a borrower's assets. filings on Oracle since 2003, both PL/SQL authors retired in 2021. In Capstone 8 you migrated it with a coordinator and five specialist subagents.

Now look back at three of those five specialists — schema-translator, plsql-converter, appsql-rewriter. Read their prompts again. None of them is really delegating work. Each one is a rulebook that happens to have a context window attached to it: the Oracle → PostgreSQL type matrix, the PL/SQL construct catalog, the rewrite rules.

That is what Agent SkillsAgent Skill — a directory under .claude/skills/ containing a SKILL.md with YAML frontmatter, optionally alongside references/ (material loaded on demand) and scripts/ (executables the agent runs). Claude loads a skill when the request matches its description. exist to hold. So this capstone takes the rulebooks out of the subagents and ships them as skills.

The thesis, stated once, because every section below returns to it:

The deliverable includes one artifact Capstone 8 does not produce: evaluation/architecture_comparison.md, a measured comparison of the two builds on the same problem. It is scored on honesty, not on the numbers being favourable. A comparison that flatters the newer architecture is a failed deliverable — it is worth nothing to the person who reads it deciding what to build next.

Prerequisites

• Capstone 8, completed and run. You need its artifacts/migration_report.json for the baseline column.
• M25 — Claude Code Mastery for the six configuration layers, and M26 for hooks and the Agent SDK.
• Docker (or Rancher Desktop) with ~6 GB free. Oracle Free 23c is a large image.
• Python 3.11+, an ANTHROPIC_API_KEY, and roughly $2 of budget per full run.

Skill or Subagent?

The question is not "which is better". It is "which problem am I solving". And it is not a two-way choice, because one frontmatter line moves a skill across the divide: context: fork makes a skill spawn a subagent, so it runs in its own window and returns only a result.

So there are three shapes, not two:

Run Capstone 8's five specialists through that last row and they sort themselves:

Notice that the honest answer already refuses to make the last one a plain inline skill. This lab makes all five inline anyway — not because that is the right production design, but because converting the one that should not be converted is how you measure what the conversion costs. You cannot price independence without giving it up once.

Keep context: fork in view while you read the rest. It is the cheapest available fix for the problem this design creates, it is one line, and The Validator Problem is where you will want it.

Animation 1: The Same Five Phases, Two Shapes

Both builds run the identical pipeline: discover, schema, data, code, validate. Watch where the knowledge lives as each phase fires.

What just happened? On the left, each phase hands its object to a specialist that starts from nothing and returns an answer. Five contexts, five fresh starts, five prompts that each carry their own copy of whatever rules they need.

On the right, one context runs the whole way through. Skills slide in when a phase needs them and slide out when it does not. The pipeline is identical; only the location of the knowledge moved.

Anatomy of a Skill

A skill is a directory, not a file. Three parts, each with a different loading cost:

That third row is the one people underuse. A scripts/ file can be run without its source ever entering the context window — the agent pays for the output, not the program. For anything deterministic, that is strictly better than reasoning:

python .claude/skills/oracle-pg-typing/scripts/check_mapping.py \
       --ddl ../legacy-oracle/01_schema.sql

  filed_date  DATE  ->  timestamp(0)
    [confident] Oracle DATE carries a TIME component. Mapping it to `date`
    silently truncates 14:32:07 to midnight, which changes which rows
    appear to have lapsed.
? records_expected  NUMBER  ->  numeric
    [check_data] NUMBER with no declared precision can carry a scale;
    narrowing it to an integer type would silently truncate.

46 columns, 20 need a look at the data.

Forty-six columns triaged, deterministically, for the cost of forty lines of output. The model now spends its judgement on the twenty that genuinely need it instead of re-deriving whether NUMBER(9) fits in an int.

Here is the real SKILL.md from the lab, trimmed to its skeleton. Note how short it is: the long material lives in references/ and is pulled in only when the agent hits the case.

---
name: oracle-pg-typing
description: This skill should be used when mapping Oracle column types to
  PostgreSQL 16 -- when the user or the migration asks to "translate a table",
  "generate DDL", "map this column", "what does NUMBER(9) become", or when any
  Oracle type name (NUMBER, VARCHAR2, DATE, RAW, CLOB, TIMESTAMP WITH LOCAL
  TIME ZONE) needs a PostgreSQL equivalent.
allowed-tools: [Read, Bash, mcp__oracle_src__oracle_get_ddl,
  mcp__oracle_src__oracle_sample_rows, mcp__pg_target__pg_apply_ddl,
  mcp__migration_local__write_artifact]
---

# Oracle to PostgreSQL type mapping

## The rule that governs everything else

**The DDL tells you the declared type. The rows tell you what the column
actually holds. Those are different questions, and the mapping depends on
the second one.**

So the procedure is always two reads, never one.

## Step 1 -- Run the checker before you reason

Load `references/type-matrix.md` for the full table, and
`references/number-precision.md` for the NUMBER(p,s) rules. Do not load
either speculatively -- they are long, and you need the context for the rows.

The Frontmatter Contract

Two keys are required. The rest are optional, and three of them decide something this capstone spends the whole page on: where the skill runs.

Every skill in this lab runs inline, and that is a deliberate experimental choice rather than a default nobody examined. One shared context is the architecture being measured against Capstone 8. The Validator Problem is where that choice costs something — and where context: fork is the lever sitting right there.

Which is why the lab asserts the contract at build time rather than hoping to notice at runtime:

# Taken from Claude Code's own schema, not from a survey of published
# skills -- a key being absent from every example you can find is not
# evidence that it is unsupported.
REQUIRED_KEYS = {"name", "description"}
OPTIONAL_KEYS = {
    "model", "allowed-tools", "disallowed-tools", "argument-hint",
    "disable-model-invocation", "user-invocable", "effort", "shell",
    "when_to_use", "paths", "hooks", "context", "agent", "background",
    ...
}
CONTEXT_VALUES = {"inline", "fork"}


@pytest.mark.parametrize("skill", SKILL_NAMES)
def test_no_invented_frontmatter_keys(skill, parsed):
    data, _ = parsed[skill]
    unknown = set(data) - KNOWN_KEYS
    assert not unknown, (
        f"{skill}: unrecognised frontmatter key(s) {sorted(unknown)}. "
        f"Claude Code ignores unknown keys silently."
    )


@pytest.mark.parametrize("skill", SKILL_NAMES)
def test_context_value_is_valid_if_present(skill, parsed):
    """`inline` expands into the conversation; `fork` spawns a subagent.
    Anything else leaves the skill running inline while its author
    believes it is isolated."""
    data, _ = parsed[skill]
    if "context" not in data:
        pytest.skip(f"{skill} does not set context (defaults to inline)")
    assert data["context"] in CONTEXT_VALUES

Animation 2: Progressive Disclosure, Measured

A subagent prompt loads whole, every time it is invoked. A skill loads in layers. Watch the token counter as the agent works through one table and only pulls in what it hits.

What just happened? The skill's entry point is small enough to keep resident. The long material — the full type matrix, the NUMBER(p,s) bands — arrives only when the agent meets a column that needs it, and the scripts/ file never enters the window at all.

The comparison against the subagent is not automatically favourable, and you should be suspicious of any page that tells you it is. A subagent's prompt is loaded once per invocation, into a context that is then thrown away. A skill's material is loaded into a context that persists for the rest of the run. Which wins depends on how many times the phase repeats and how much of the reference material actually gets touched.

Animation 3: The Phase → Skill Map

A subagent's tools: frontmatter stops it reaching things it has no business touching. The skills build needs the same containment, and gets it from the SDK.

PHASE_SKILLS: dict[str, list[str]] = {
    "discover": [],
    "schema":   ["oracle-pg-typing"],
    "data":     ["nullability-preservation"],
    "code":     ["plsql-conversion", "appsql-rewriting"],
    "validate": ["migration-validation", "nullability-preservation"],
    "cutover":  [],
}

Three decisions in that map are worth defending out loud:

• discover loads nothing. Taking an inventory needs no rulebook. Loading the type matrix here would put it in the window for the whole run to no purpose.
• data cannot load migration-validation. The phase doing the work must not be able to reach the procedure that decides whether the work was correct. It could not mark its own homework even if it tried.
• nullability-preservation appears twice. That is the next section, and it is the strongest argument this architecture has.

One File, Two Phases

Go back to Capstone 8 and open two files side by side: .claude/agents/data-migrator.md and .claude/agents/migration-validator.md. Both contain a description of the empty-string trap. They have to — the loader needs to know how to avoid it, and the validator needs to know how to detect it.

They are two copies of one rule, and nothing keeps them in step.

Edit the rule in 8B and both phases change together, because there is only one of it. That property is asserted, not assumed:

def test_nullability_skill_is_shared_by_two_phases():
    """The reuse argument, asserted rather than claimed.

    If this ever becomes one phase, the architecture's headline benefit over
    copy-pasted subagent prompts has quietly gone away.
    """
    mapping = _phase_skills()
    phases = [p for p, skills in mapping.items()
              if "nullability-preservation" in skills]
    assert sorted(phases) == ["data", "validate"]

The same idea shows up once more in the lab, one level down. plsql-conversion ships no scanner of its own — it calls the one bundled with appsql-rewriting. One construct catalog, two consumers, so the phase that rewrites application SQL and the phase that converts PL/SQL can never disagree about what counts as an Oracle-ism.

Animation 4: Context Growth Across Six Tables

Phases 2 and 3 each iterate the six tables. Watch what happens to the context window under each architecture.

What just happened? The subagent line is a sawtooth — each table gets a fresh window that is discarded when the specialist returns. The skills line climbs and does not come back down, because every table's DDL, sample rows and decisions stay in the one conversation.

Read that carefully, because the shape alone does not tell you which is better. A monotonic climb is only a problem if it reaches the ceiling; below the ceiling, the accumulated context is the thing that lets phase 4 remember what phase 2 decided. Six tables and 19,065 rows is comfortably inside a 200K window. Six hundred tables would not be.

Tool or Script? The One That Moved

Capstone 8's tools_local.py exposed two MCP tools. 8B's exposes one. scan_app_sql is gone, and the same regex now ships as appsql-rewriting/scripts/find_oracleisms.py.

That last row is why write_artifact stays a tool. It is not knowledge — it is the thing that confines every generated file to artifacts/, and that boundary has to hold in phases where no relevant skill is loaded at all. A capability that must always be true cannot live somewhere that is only sometimes loaded.

Read the module docstring the lab ships in place of the deleted tool — the absence is documented, because a future reader will otherwise assume it was an oversight:

"""Local (non-database) tools: artifact writing.

## What is NOT here, and why

The subagent build of this migration (Capstone 8) also exposed a
`scan_app_sql` MCP tool here. In the skills build it is gone -- the same
scanning logic now ships as
`.claude/skills/appsql-rewriting/scripts/find_oracleisms.py`, and the agent
runs it with Bash.

  MCP tool     always present, described in every request's tool list,
               costs context whether or not this phase needs it, and its
               *rationale* lives somewhere else entirely.

  Skill script loaded only when the skill loads, and it sits next to the
               SKILL.md that explains when to run it and how to read the
               output.

`write_artifact` stays an MCP tool, because it is genuinely a capability
rather than knowledge: it enforces the artifacts/ confinement boundary, and
that boundary must hold in every phase regardless of which skills happen to
be loaded.
"""

Animation 5: The Validator Problem

This is the cost. Everything above was instrumentation for measuring it.

In Capstone 8, migration-validator started from an empty context. It had never seen the reasoning that chose timestamp(0) over date, or the decision to let null_as default. When it said "all clear", that was an opinion formed independently of the work.

In 8B, phase 5 is phases 2 through 4. Everything it is auditing is already in its context, written by it, and — from its point of view — already justified.

Note carefully what this is and is not. It is a consequence of this lab running every skill inline, not an inherent property of skills: context: fork would give the validator its own window. The inline choice is what makes the cost measurable, and the fork is the fix waiting at the end of the measurement.

The lab compensates in two places. First, in the skill itself:

### The bias you are running with

In the subagent build of this migration, validation ran in its own context and
had never seen the loading decisions. **Here it does not.** You are the same
context that chose the type mappings and ran the loads. You will be inclined to
accept your own work.

Two rules follow, and they are not optional:

1. **Re-derive every number from the database.** Never report a count you
   remember writing. If you did not just query it, you do not know it.
2. **Assume the load is broken until a query says otherwise.** Start from
   suspicion, not from your recollection that phase 3 went fine.

Second, in the phase prompt, which says the same thing in the imperative. And then — because an instruction is a hope, not a mechanism — the lab makes you measure whether it worked.

The second column is answerable from the audit log rather than from the prose the agent produced:

import json
calls = [json.loads(l) for l in open("migration_audit.jsonl", encoding="utf-8")]
reads = [c for c in calls
         if "pg_query" in c["tool_name"] or "pg_row_count" in c["tool_name"]]
print(f"{len(reads)} target reads during the run")

If phase 5 emitted no reads against the target, it did not re-derive anything — it reported from memory, and a clean result from it means nothing at all. That is a measurable property, not a vibe, and it is the single most important number in the whole comparison.

Three ways out, and they are not equivalent

Once you have the numbers, the interesting part is what you do about them. There are three fixes, in increasing order of what they cost you:

The middle row is the one this capstone exists to surface. It is one line of frontmatter. It buys back exactly the property the inline design gave up — a context that has not seen the work — without giving up the single shared file that made the skills architecture worth building. Whether it is enough is an empirical question, which is why Going Further asks you to run the three trials again with the validator forked.

Animation 6: Guardrails, Unchanged

Three PreToolUse guards and a PostToolUse audit log. They are byte-identical to Capstone 8's, and the point of showing them again is that nothing about them needed to move.

What just happened? Nothing changed — and that is the finding. Guardrails sit between the agent and the tools, so they are indifferent to how the agent's knowledge is organised. hooks.py, hooks_cli.py and .claude/settings.json carried across untouched.

When a Skill Silently Does Not Load

Two ClaudeAgentOptions fields make skills work. Both are required, and omitting either produces no error.

return ClaudeAgentOptions(
    model=model,
    system_prompt=system_prompt,
    mcp_servers={...},
    can_use_tool=hooks.can_use_tool,
    hooks=[HookMatcher(matcher="*", hooks=[hooks.audit_log])],
    # Without this, `.claude/skills/` is never read and every skill
    # silently does not exist. The agent then improvises the type
    # mapping from memory and the run looks like it worked.
    setting_sources=["project"],
    # Per-phase allowlist. `None` would mean "no skills"; `"all"` would
    # mean every discovered skill in every phase, which defeats the
    # scoping this architecture depends on.
    skills=skills,
)

Miss setting_sources and the skills directory is never opened. Miss skills and nothing is selected. In both cases Claude answers from its own knowledge of Oracle and PostgreSQL — which is quite good, and that is precisely the problem. The DDL it generates will be plausible. It will also have decided DATE on its own.

grep -c "check_mapping" migration_audit.jsonl    # must be > 0
python coordinator.py --list-skills             # sanity-check the map first

File Structure

Everything that is not agent logic ships complete. You build the skills, the phase map, the guardrails, and the comparison.

Note what is absent from the root, compared with Capstone 8: no type_mapping.py, no oracle_constructs.py, no validation.py, and no .claude/agents/ at all. That logic moved inside the skills that explain it. If you generate this project from the spec and those files come back, the generator produced the Capstone 8 shape.

Spec-Driven: Build It Twice

This is a Tier 3 capstone, so the spec is the source and the solution is the reference:

/generate-from-spec spec/agent-spec.md      # writes into generated/
diff -r generated/ solution/                # where they differ, decide who is right

Then do the thing this capstone makes possible and Capstone 8 alone does not: read the two specs side by side.

Four sections differ out of twelve. Everything you would call "the safety architecture" is in the eight that do not. That is the most reusable thing on this page: the skills-versus-subagents question is a question about where knowledge lives, and it is close to orthogonal to how the system is made safe.

Step-by-Step Build Guide

# Credentials
cp starter/.env.example starter/.env
# Edit starter/.env and add your ANTHROPIC_API_KEY

pip install -r requirements.txt

docker compose -f starter/docker-compose.yml up -d

# WAIT. This is the step people skip.
# oracle must read "healthy", not just "running".
docker compose -f starter/docker-compose.yml ps

# Work through the TODOs in these four files:
#   oracle-pg-typing/scripts/check_mapping.py          TODO(1)-(12)
#   appsql-rewriting/scripts/find_oracleisms.py        TODO(1)-(10)
#   nullability-preservation/scripts/compare_nulls.py  TODO(1)-(7)
#   migration-validation/scripts/compare_checksums.py  TODO(1)-(11)

# Each carries its own cases:
python starter/.claude/skills/oracle-pg-typing/scripts/check_mapping.py --self-test

# Then point it at the real thing -- this is the discovery step:
python starter/.claude/skills/oracle-pg-typing/scripts/check_mapping.py \
       --ddl legacy-oracle/01_schema.sql

TEST_TARGET=starter pytest tests/test_skills_wellformed.py -v

cd starter
python coordinator.py --list-skills

python coordinator.py --migrate-all

python coordinator.py --phase cutover                     # must be denied
python coordinator.py --phase cutover --approve-cutover   # only a human

python evaluation/test_suite.py            # must score >= 18/20

# The validator-independence trials -- run this THREE times:
#   1. break phase 3 (omit null_as)
#   2. python coordinator.py --phase validate
#   3. record whether it caught its own mistake, and whether it re-queried
python - <<'EOF'
import json
calls = [json.loads(l) for l in open("migration_audit.jsonl", encoding="utf-8")]
reads = [c for c in calls
         if "pg_query" in c["tool_name"] or "pg_row_count" in c["tool_name"]]
print(f"{len(reads)} target reads during the run")
EOF

Measuring It Yourself

The baseline column is pre-filled from Capstone 8's reference run — a clean second run, after the empty-string defect was fixed. The 8B column is deliberately empty on this page, because publishing invented numbers for the new architecture would destroy the one thing this capstone teaches.

Capstone 8 queued three items for manual review. A migration that queues fewer is not doing better — it is either finding less or guessing more:

1. PKG_FILING_MAINT.log_audit — PRAGMA AUTONOMOUS_TRANSACTION, no in-process equivalent
2. MV_STATE_ROLLUP — PostgreSQL materialized views have no fast refresh and no query rewrite
3. RiskReportDao.java:lapsingSoon — date - date is a NUMBER in Oracle and an INTERVAL in PostgreSQL, and the Java reads it with rs.getInt()

Before you measure, write down a prediction. Which phases should get cheaper under skills, and which more expensive? What happens to schema, which runs six times and reloads the same rulebook each time? Then check yourself. The gap between your prediction and the measurement is the part worth keeping.

Test Cases

The twenty evaluation scenarios are identical to Capstone 8's. That is what makes the two scores comparable, and it is why you must not "improve" them.

pytest tests/ -v                       # grades solution/ by default
TEST_TARGET=starter pytest tests/ -v   # grades your work
python evaluation/test_suite.py        # the 20 scenarios; >= 18 to pass

The solution suite is 199 tests green. A fresh starter gives 39 passes and 160 failures.

📂 Get the files: labs/capstone-8b-skills-first on GitHub — or clone the course once: git clone https://github.com/varasrinivas/agenticai-course.git

Troubleshooting

Going Further (all OPTIONAL)

• Add a sixth skill to the spec. Put index-strategy in spec/agent-spec.md, regenerate, and compare the cost of that change against adding a sixth subagent to Capstone 8's spec.
• Give phase 5 its independence back. Run --phase validate in a fresh process, so it has the session file but not the conversation. Does the validator behave more like Capstone 8's? Record it — this is a cheap experiment with a genuinely uncertain answer.
• Build the hybrid. Keep the four knowledge skills and restore migration-validator as a subagent. Measure whether it recovers Capstone 8's validator reliability while keeping 8B's shared knowledge. If the measurements support the hybrid, that is the right answer and your write-up should say so.
• Fork the validator. Add context: fork to migration-validation/SKILL.md and re-run the three independence trials. This is the cheapest fix for the validator problem and the one the frontmatter puts within reach — measure whether it actually recovers Capstone 8's reliability, and what it costs in tokens and wall clock.
• Make a skill user-invocable. Add user-invocable: true to oracle-pg-typing and call it directly from Claude Code to triage a table by hand.

References & Resources

The lab

• labs/capstone-8b-skills-first/README.md — setup and the done-when list
• labs/capstone-8b-skills-first/spec/agent-spec.md — the canonical spec; read it beside Capstone 8's
• labs/capstone-8b-skills-first/solution/.claude/skills/ — the five reference skills
• labs/capstone-8b-skills-first/tests/test_skills_wellformed.py — the frontmatter contract, asserted
• labs/capstone-8b-skills-first/solution/evaluation/architecture_comparison.md — the deliverable

Elsewhere in this course

• Capstone 8 — the subagent build. Required reading for this one.
• M25 — Claude Code Mastery — the six configuration layers
• M26 — Hooks, Sessions & the Agent SDK — where the guardrails come from
• M14 — Multi-Agent Systems — when delegation genuinely earns its cost

Primary sources for the frontmatter contract

• Claude Code's own frontmatter schema — the authority on which keys exist and what each does. It is the only source that settles the question; the two below are useful but neither is complete.
• plugin-dev/skills/skill-development/SKILL.md in the official Anthropic plugin marketplace — good on the scripts/ / references/ / assets/ layout and on writing a description that triggers reliably. It does not document every key.
• The skills shipped in that marketplace — useful for house style, but a key appearing in none of them is not evidence it is unsupported. context is exactly that case: absent from every published example, and fully supported.