Agent Skills moved to the Linux Foundation. Here’s which of my SKILL.md files survived, and why most of them didn’t.

On 22 October, Anthropic handed Agent Skills to the Agentic AI Foundation, the Linux Foundation project that already looks after MCP and AGENTS.md. SKILL.md stopped being one company’s file format and became an open standard.

Eight days later, I moved three of my own skills into a folder called skills-archive.

That timing looks like bad luck. It isn’t. The standard and my archive folder are answering the same question: what is a skill actually for, now that the models are this good?

What actually changed on 22 October

Less than the headlines suggest, and that’s the point.

According to coverage of the announcement, the donation covers the Agent Skills name, logo, GitHub organisation and the agentskills.io domain. Anthropic says more than 70 agent platforms already read the format, including ChatGPT, Cursor, GitHub Copilot and VS Code. Your existing SKILL.md files keep working. Nobody has to join anything to use them.

The format itself is small. A skill is a folder with a SKILL.md file in it, plus optional scripts and reference files. The specification requires two frontmatter fields, name and description. An agent loads only those two at startup and reads the rest of the file when a task matches.

So the news isn’t “skills got better”. It’s “skills now belong to everyone, so whatever you put in them should be worth carrying between tools”. That made me look hard at mine.

Why I wrote skills in the first place

I didn’t write skills because they were elegant. I wrote them because I was tired.

Earlier models had much less context and much less memory. Every time I wanted to turn a draft into an X thread, or an article into an Instagram carousel, I had to explain the whole workflow again: the format, the voice, the file paths, the rules I’d learned the hard way. Putting it all in CLAUDE.md wasn’t enough to make it stick.

So I wrote it down as skills. Lots of it.

By June I had three content skills doing most of the work:

That’s about 11,500 words of instructions. The writing skill even chained into the others: its step 5.7 offered to run the Instagram skill when the Reddit posts were done. I had built a workflow engine out of markdown files, because the model couldn’t hold the workflow in its head.

What changed: the model can hold the workflow now

I now run Opus 5.5 on high effort as the orchestrator. It plans, makes the design calls, and keeps track of what happens next. It holds a whole content workflow in context without me spelling it out step by step.

When I restructured my content folder this week, the 11,500 words of skills turned into two short documents: a strategy file (who I write for, what channels I use, how often) and a CLAUDE.md that explains where things live. The model reads those, asks me what it needs, and does the rest.

The skills had been doing two different jobs, and I hadn’t noticed:

1. Remembering the workflow. Which step comes next, what the output should look like, what to check.
2. Doing a repeatable job. Producing the same kind of output, the same way, every time.

A strong orchestrator makes the first job unnecessary. It doesn’t make the second one go away.

The skills that stay

Most of the skills I still use do implementation work: building and updating parts of a project, or updating the artifacts I track my work in. I run most of them on Sonnet 5.5, not Opus.

That’s the split that makes sense to me now:

• Opus 5.5, no skill: planning, judgment, design decisions, deciding what to do next. These change every time, so writing them down as fixed steps makes them worse.
• Sonnet 5.5, with a skill: jobs where I already know exactly what “done” looks like. The skill is a recipe, and a cheaper, faster model follows a good recipe just fine.

The one new skill I wrote this week fits that pattern. It’s called /radar: it scans recent news for my content pillars, writes a dated note in a fixed format, and suggests what's worth posting about. Same inputs, same output shape, twice a week. That's a skill.

Deciding which of those news items is worth an article, and what I actually think about it? That’s not a skill. That’s me and the orchestrator.

Checking my files against the standard

If skills are now portable, the ones I keep should follow the spec. So I checked my three archived skills against it.

Only one of the three was clean. koriigami-write-article uses just name and description, which is exactly what the spec asks for.

The other two had habits I’d picked up along the way:

• koriigami-post-x lists allowed-tools as a YAML list. The spec describes it as a space-separated string, and marks the field as experimental.
• koriigami-post-instagram-kagadmodyaa adds its own top-level type and version fields. The spec has a metadata block for extra information like that. It's also 805 lines long, where the spec recommends keeping SKILL.md under 500 and moving detail into separate reference files.

None of this broke anything in Claude, which is part of the problem. A tool that tolerates your quirks doesn’t tell you they’re quirks.

I should be honest about the bigger gap. I’ve only ever run my skills in Claude. I haven’t loaded one in Codex, Cursor or anything else, so I can’t tell you what transfers cleanly and what doesn’t. That’s the next thing I’m testing, with /radarfirst, because it's small and I use it every week.

What I’m changing

1. Workflow and judgment go in plain documents, not skills. A strategy file and CLAUDE.md, read by a model that’s good enough to use them.
2. Skills are for repeatable jobs. If I can’t describe what “done” looks like in advance, it isn’t a skill yet.
3. Repeatable jobs run on Sonnet 5.5. Opus plans; Sonnet executes the recipe.
4. Every skill I keep follows the spec. name and description up front, anything extra under metadata.
5. No portability claims until I’ve tested one. If a skill only works in one tool, it’s a prompt with a filename.

The standard didn’t make my old skills obsolete. Better models did. What the standard did was make me ask which of my skills I’d bother taking with me to another tool. For most of them, the honest answer was none. For the few that are left, it’s all of them.

Originally published at koriigami.com on October 31, 2026.

Andrej Karpathy shared a deceptively simple pattern in April 2026. Instead of RAG, have Claude maintain a structured markdown wiki that compounds as you add to it.

In April 2026, Andrej Karpathy (OpenAI co-founder, former Tesla AI Director) published a GitHub Gist called “LLM Wiki.” It got 5,000+ stars within days. Not because it was technically impressive. Because it was surprisingly simple.

The premise: instead of building a RAG pipeline with embeddings and vector search, you have Claude Code maintain a structured collection of markdown files. You dump in raw sources. Claude organizes them. You ask questions. Claude searches its own index and answers with citations linking back to specific wiki pages.

Karpathy’s own reaction was the most honest part: “I thought I had to reach for fancy RAG, but the LLM has been pretty good about auto-maintaining index files.”

That’s it. That’s the idea. Here’s how to build it.

Why RAG doesn’t work well for personal notes

If you’ve ever set up a RAG pipeline for your own documents, you’ve probably hit this: the retrieval works fine for direct questions but falls apart on synthesis. Ask “what did that paper say about X?” and you get an answer. Ask “how does X relate to the patterns I’ve been noticing across the last three projects?” and you get something generic that ignores half of what’s in your collection.

The reason is structural. RAG has no accumulation. Every query starts from scratch: retrieve, rank, inject into context, generate. If the answer requires synthesizing five documents, the system has to find all five, hope the retrieval worked, and stitch them together on the fly. There’s no memory of connections you’ve already made, no building on earlier synthesis.

There’s another problem with RAG that’s underappreciated: retrieval failures are silent. The system doesn’t tell you it didn’t find the relevant chunk. It just generates a response without it, and you can’t tell whether the answer is complete or missing something important.

For personal knowledge (your notes, your research, your patterns across projects), neither of these tradeoffs is acceptable. You want answers that reflect your actual context, not a best-effort retrieval pass.

The LLM wiki pattern: what it actually does differently

The core idea is simple once you see it. Instead of searching your notes at query time, you have Claude pre-process them into a structured wiki. Connections get made when you ingest a source, not when you ask a question. The wiki accumulates knowledge the way a notebook does, except Claude writes the notebook.

Three layers, each with a clear role:

Raw sources are immutable. PDFs, articles, transcripts, images, meeting notes: everything you feed the system. Claude reads from here but never writes to it. This is your record of what actually exists.

The wiki is Claude’s layer. A directory of markdown files: concept pages, entity pages, comparison pages, synthesis pages. Claude creates and updates these as you ingest new sources. Each page links to others using [[wikilinks]]. Over time, the connections accumulate. Claude is responsible for maintaining them.

The schema is a CLAUDE.md file that tells Claude how the wiki works: what the folder structure is, what conventions to follow, what to do when it ingests a new source, how to handle contradictions between pages. If you've read my earlier piece on CLAUDE.md, this is the same pattern: encode the rules once, let Claude follow them consistently.

The reason this works at personal scale is context. For knowledge bases under roughly 100,000 tokens (call it 500–1,000 average-length notes), Claude can hold the index in context and reason over it directly. No embeddings, no vector database, no infrastructure to maintain.

Three operations you’ll use every day

Ingest

You found something worth keeping. An article, a paper, a set of notes from a meeting. You save it to your raw/ folder and tell Claude to ingest it.

Claude reads the source, creates or updates wiki pages (a summary page for the source itself, concept pages for any new ideas it introduces, entity pages for people or projects mentioned), and updates the index file so future queries can find it. Then it marks the source as processed.

The result: the source is in your collection, its key ideas are on wiki pages that link to each other, and the index knows it exists.

Query

You ask a question. Claude searches the wiki (starting with the index, pulling relevant pages) and answers with citations that link directly to specific wiki pages, not back to raw sources. Because the wiki pages already contain synthesis, the answers can reference connections across multiple sources without repeating that work.

This is the payoff. A question that would require RAG to stitch together five documents just requires Claude to read the wiki pages it already built when those documents came in.

Lint

The wiki gets messy over time. Dead links, orphan pages, contradictions between what you thought two years ago and what you know now, stale pages that reflect outdated understanding. You run lint and Claude checks for all of it, fixing what it can automatically and flagging what needs your attention.

This is what makes the system compound. Not just accumulating pages, but maintaining the quality of the connections between them.

How to set this up with Claude Code and Obsidian

This takes about 30 minutes to get running for the first time.

Step 1: Create your vault structure.

Create a folder for your wiki (~/wiki or wherever makes sense). Inside it:

wiki/
├── raw/              ← immutable sources go here
│   ├── articles/
│   ├── papers/
│   └── notes/
├── wiki/             ← Claude's markdown pages
├── index.md          ← Claude maintains this automatically
└── CLAUDE.md         ← your schema

If you want an Obsidian view, open Obsidian and point it at this folder as a new vault. Everything stays in plain markdown, with no lock-in.

Step 2: Write your CLAUDE.md schema.

This is the most important file. It tells Claude exactly how your wiki works. Start from Karpathy’s original gist and adapt it, or use one of the community implementations as a starting point. nvk/llm-wiki and Ar9av/obsidian-wiki are both solid bases.

Your schema should define: what the folder structure means, how to name wiki pages, what sections every page should have, how to handle contradictions, and the exact commands for ingest/query/lint.

A minimal version for the ingest operation looks like:

## Ingest command
When I say "ingest [filename]":
1. Read raw/[filename]
2. Create wiki/[slug].md with: summary, key concepts, related pages
3. Update or create concept pages for any new ideas
4. Add entry to index.md
5. Mark source as processed in raw/ (add a .processed suffix or move to raw/done/)

Step 3: Ingest your first sources.

Open Claude Code with your wiki folder as the working directory. It will read your CLAUDE.md automatically. Then:

ingest articles/that-paper-i-saved.pdf

Claude processes it, creates wiki pages, updates the index. Do this with a handful of sources to see the structure before you decide if you want to adjust anything.

Step 4: Ask your first question.

What have I captured about [topic]? Summarize the key patterns and link to the relevant wiki pages.

The first few times you do this, the wiki will be sparse and the answers limited. That’s fine. The system compounds: the more you ingest, the more useful the queries become.

Step 5: Schedule a weekly lint.

Add a reminder to run lint once a week. Ten minutes of cleanup keeps the wiki useful as it grows. Without it, dead links accumulate and pages diverge from each other.

A few things to get right from the start

Keep raw sources immutable. The moment you let Claude edit source files, you lose track of what was original and what was generated. Raw files are your ground truth. Only the wiki layer gets modified.

Write the schema before you ingest anything. If you start ingesting without a schema, Claude will make up conventions on the fly and they’ll be inconsistent. Twenty pages in, you’ll be retrofitting structure to a mess. Write the CLAUDE.md first, even if it’s minimal.

Don’t index everything. RAG pipelines tempt you to throw everything in. The LLM wiki works best when you’re intentional. If a source isn’t worth reading again, it’s not worth ingesting. The index quality matters more than the index size.

Know the scale limit. The approach works reliably below roughly 50,000–100,000 tokens of wiki content. For most personal knowledge bases, that’s a long way off. When you approach it, you’ll know; queries will start getting slower and less coherent. At that point, a hybrid approach with a retrieval layer makes sense.

Start small, then let it compound

The first instinct is to migrate your entire Notion or Roam database on day one. Don’t. Don’t. Start with five sources in one domain, a subject you’re actively thinking about. Ingest them, query them, see how the wiki pages look.

The value of this system comes from time, not volume. A wiki with 50 deeply connected pages is more useful than a wiki with 500 loosely indexed ones. Ingest consistently. Lint regularly. Let Claude maintain the connections. That’s the whole pattern.

Karpathy called it “surprisingly viable.” After a few weeks with it running in the background, I’d say that’s underselling it.

Originally published at koriigami.com on May 23, 2026.

Configure a prompt, attach a repo, pick a trigger. Claude runs it on Anthropic’s infrastructure: no laptop, no cron job, no babysitting.

There’s a category of work that’s genuinely repetitive: the Monday morning dependency scan, the PR summary that should auto-generate every time a branch is merged, the weekly competitive brief that takes 20 minutes to pull together but could be done by Claude in the background.

You know Claude could do these. But Claude only works when you’re in a session, which means you either start the session yourself, every time, or the task doesn’t happen.

Claude Code Routines, launched April 14, 2026, closes that gap. A routine is a saved configuration: a prompt, one or more GitHub repositories, and a set of connectors. Set it once. It runs on Anthropic’s cloud infrastructure (on a schedule, triggered by a GitHub event, or fired via API) with no approval prompts, no open laptop required.

This isn’t another Zapier. Zapier routes data between apps. Routines write code, read files, run analysis, and commit results. The output is Claude Code’s output: actual work product, not just a triggered notification.

What a routine actually is

A routine is not a background process on your machine. It runs in an Anthropic-managed cloud container, the same environment as Claude Code on the web. Your repo is cloned fresh at the start of each run. Claude executes its task. Any outputs (files edited, branches created, commits pushed) go directly to GitHub under your identity.

Three things define a routine:

A prompt. This has to be self-contained. There are no approval prompts during a run; Claude cannot ask clarifying questions or request confirmation. What you write in the prompt is the entire brief. Vague prompts produce vague routines.

One or more GitHub repos. Every routine needs at least one repository. The repo is cloned from the default branch at the start of each run. By default, Claude can only push to branches prefixed with claude/. To push to main or any existing branch, enable that per-repo in the settings.

Connectors. Any MCP connectors you’ve added to your Claude Code account are available to routines. Slack, Linear, Notion, GitHub, whatever you’ve connected. All included by default; remove what the routine doesn’t need.

Run limits: Pro gets 5 runs/day, Max gets 15, Team and Enterprise get 25. One-off scheduled runs don’t count against these caps.

Setting one up

Go to claude.ai/code/routines and click “New routine.” Seven steps, most of them quick:

1. Name it: something descriptive that will make sense in a list of routines
2. Write the prompt: specific, imperative, self-contained (more on this below)
3. Select repos: the repositories this routine will clone and potentially modify
4. Choose an environment: controls network access and available packages; the default works for most cases
5. Pick a trigger: schedule, GitHub event, API, or any combination
6. Review connectors: remove any the routine doesn’t actually need
7. Create, then “Run now” to verify the first run before relying on it

From the CLI, /schedule accepts natural language: /schedule daily dependency scan at 9am creates a routine directly. You can manage them with /schedule list, /schedule update, and /schedule run.

One setup gotcha: GitHub event triggers require the Claude GitHub App installed on the target repository. This is a separate step from the standard GitHub auth (/web-setup). If the GitHub App isn't installed, event triggers silently won't fire. Install it from the repository settings or from the routine configuration UI before relying on event-based triggers.

Writing a prompt that works autonomously

The biggest failure mode for routines is a prompt written as if Claude can ask follow-up questions. It can’t.

Bad: Review open PRs and summarize them.

Good: Review all open pull requests in the repository that have been open for more than 3 days and have no reviewer assigned. For each PR: read the diff, write a 2-3 sentence plain-English summary of what it changes, identify any obvious risks or missing tests, and post a comment on the PR with your findings. Sign off comments with "- Routine Review".

The second version leaves no ambiguity. Claude knows exactly what to look at, what to produce, and where to put it.

Three trigger types

Schedule. Recurring runs at whatever cadence you set: hourly, daily, weekdays only, weekly. Minimum interval is one hour. Useful for anything time-based: morning briefings, weekly reports, end-of-week commit summaries.

GitHub event. Fires when something happens in the repo: PR opened, PR closed, PR labeled, release published. You configure filters by author, title, base branch, labels, and draft status to control exactly which events trigger a run. Useful for automating responses to repo activity without building a custom GitHub Action.

API. Each routine gets a unique POST endpoint and bearer token. Hit it from anywhere: a webhook, another script, a mobile shortcut. Pass optional context in the text field (the contents of an alert, the body of an incoming message). Useful when you want to trigger Claude from an external system.

A single routine can use all three simultaneously.

Who this is for (beyond developers)

Most coverage of Routines focuses on engineering workflows. That’s the obvious use: automated code review, dependency scanning, PR summaries. But the feature isn’t limited to people who write code for a living. Any role with repetitive research, synthesis, or reporting tasks and a GitHub-hosted repo to work from can benefit.

Here are four perspectives:

Developer

Dependency audit (weekly, Monday 8am): Scans for outdated or vulnerable packages, generates an upgrade plan with breaking change notes, and posts it as a GitHub issue. You see it in your inbox Monday morning.

PR summary on merge (GitHub event: PR closed): Filters for PRs where is merged = true. Writes a human-readable changelog entry from the diff and commits it to CHANGELOG.md on a claude/changelog branch. Review and squash-merge weekly.

Test coverage gap report (weekly): Runs coverage analysis, identifies untested functions, and opens a GitHub issue ranking them by call frequency. Makes the “what should we test next” decision obvious rather than manual.

Product designer

Competitor UI monitor (weekly): Tracks a list of competitors in a competitors.md file. Searches for product update announcements, screenshots, and changelog entries. Generates a structured summary: what changed, what it means for your current design decisions.

Design handoff checklist (GitHub event: PR opened with label “design-handoff”): When a PR tagged design-handoffopens, the routine reads the linked spec file, generates an implementation checklist for the dev team, and posts it as a PR comment. Reduces back-and-forth between design and engineering.

User research synthesis (GitHub event: new file in /research/transcripts/): When a new transcript is pushed, the routine extracts themes, groups them by journey stage, and appends findings to /research/synthesis.md. The synthesis document stays current without a dedicated synthesis session.

Product manager

Sprint planning prep (Monday, before standup): Reads the current sprint backlog from a connected Linear or GitHub Projects board, maps items against estimated capacity, and generates a ranked list of what should make the sprint. Takes 30 seconds to review instead of 30 minutes to build.

Release notes on merge (GitHub event: PR merged to main with label "release"): Reads the diff, writes a user-facing release note in plain English, and appends it to RELEASES.md. By the time you're ready to communicate the release, the draft is already there.

Stakeholder update (Friday, 4pm): Pulls open issues, merged PRs, and sprint progress for the week. Generates a non-technical summary paragraph suitable for the weekly team email. You edit the tone; you don’t write the first draft.

CEO / Founder

Executive digest (daily, 7am): Reads a priorities.md file you maintain in the repo, pulls recent GitHub activity across connected repos, and generates a one-page morning brief: what shipped, what's blocked, what needs a decision today.

OKR health check (biweekly): Cross-references a okrs.md file against recent commits and issues. Generates a status summary per objective: on track, at risk, or stalled. Evidence comes from actual repo activity, not self-reported status.

Board memo first draft (monthly, 1st of the month): Reads kpis.md, okrs.md, and recent activity. Generates a structured board update draft: what was planned, what shipped, what's next, what decisions are needed. You edit and finalize; you don't start from a blank page.

When not to use Routines

When the task needs your judgment mid-run. Routines are fully autonomous. If the task has a branch point (“if X, do Y; if Z, ask me first”), that ask-first path doesn’t exist. Either the prompt handles the branching explicitly, or the task isn’t right for a routine.

When you need local file system access. Routines run in Anthropic’s cloud. They clone your GitHub repos and can read/write files within them, but they can’t touch files on your machine or inside your private network.

When the task takes less than 5 minutes and you’re already at your desk. For quick one-off tasks, just open a Claude Code session. The overhead of configuring and maintaining a routine only pays off when the task recurs reliably.

When you’re under the run limit on the wrong plan. Five runs per day on Pro sounds like a lot until you add a daily briefing (1), a weekly report (not daily but averages), two event triggers that fire on active repos, and a Monday planning routine. Prioritize before you configure.

The shift it represents

Every role has tasks that should happen on a cadence but don’t, because the friction of starting them is higher than the value of doing them once. They end up on a mental list of “things I should do regularly” that never quite makes it to “things I actually do regularly.”

Routines are the infrastructure for closing that gap. Recurring work moves off your plate entirely, done in the background, waiting in your inbox when you need it.

Nick Spisak’s summary is the cleanest mental model for when each Claude Code mode applies: use a routine when you want to set it and forget it, use a desktop schedule when you need local access, use /loop when you need it right now. Three modes, three different jobs.

Configure one routine this week. Something you actually do on a recurring basis, not something theoretical. See how the output compares to what you’d produce manually, and adjust the prompt from there.

Sources

[1] Introducing routines in Claude Code: Anthropic Blog. Launch announcement, April 14, 2026. Official framing and feature overview.

[2] Automate work with routines: Claude Code Docs. Full setup documentation: trigger types, run limits, GitHub App requirement, environment configuration, branch permissions.

[3] Claude Code Routines discussion: Hacker News. 720 points, 413 comments. Community reaction including vendor lock-in concerns and practitioner perspectives.

[4] Nick Spisak routine/schedule/loop breakdown: X. Three-mode mental model: routine (set and forget), desktop schedule (local access), /loop (right now).

Originally published at koriigami.com.

The benchmarks are real. So is the 35% tokenizer surprise. Here’s what changed and how to decide if now is the right time.

Every model release comes with the same question: is this worth switching?

With Opus 4.7, the answer is more complicated than usual. The headline is accurate: same 5/25 pricing, real benchmark gains across 12 of 14 reported tests. But three things make this upgrade decision less obvious than it looks: a new tokenizer that can raise your real costs by up to 35%, a set of breaking API changes that require code updates, and at least one workflow type where 4.7 performs worse than 4.6.

This is a practical breakdown, not a benchmark post. The goal is a clear decision framework for whether to switch now, switch carefully, or hold.

What’s genuinely better

The gains in Opus 4.7 are real and concentrated in specific areas.

Coding benchmarks jumped significantly. SWE-bench Pro climbed from 53.4% to 64.3%, and SWE-bench Verified went from 80.8% to 87.6%. CursorBench, which tests real-world coding inside an IDE environment, went from 58% to 70%. These are not marginal improvements.

Agentic efficiency improved by 2x. Opus 4.7 averaged 7.1 LLM calls to complete the same tasks that Opus 4.6 needed 16.3 calls for. p50 latency dropped from 242 seconds to 183 seconds. The model is also 60% less likely to drop subtasks in long agentic sequences compared to its predecessor. For multi-step agentic workflows, this is the most consequential improvement in the release.

The model proactively verifies its own work. In agentic contexts, Opus 4.7 writes tests, runs them, and fixes failures before surfacing results. This “verify before reporting” behavior reduces back-and-forth on complex tasks without you having to prompt for it explicitly.

Vision capability changed dramatically. Vision accuracy went from 54.5% to 98.5%, and maximum image resolution tripled from 1568px to 2576px (1.15MP to 3.75MP). The model can now read small text in screenshots, parse dense UI mockups, and extract information from high-resolution photos that previous versions couldn’t process cleanly. If your workflows involve image analysis or document processing, this is a substantial capability change.

The new effort system

Opus 4.7 ships with a redesigned effort parameter.

The scale now has five levels: low, medium, high, xhigh (new), and max. Anthropic recommends starting with xhigh for coding and agentic use cases, and the internal benchmark numbers support that: xhigh scores approximately 71% on the Agentic Coding benchmark while consuming around 100k tokens. Max effort only reaches 74.5%, but consumes over 200k tokens. For most production workloads, xhigh is the better cost-performance tradeoff.

The practical change from Opus 4.6 here is not just the new level; it’s that you now have explicit control over where the model sits on the intelligence-vs-cost curve.

There’s also a new task budgets feature in beta. Pass the task-budgets-2026-03-13 beta header and add task_budget: {type: "tokens", total: N} to output_config, with a minimum of 20k tokens. The model sees a running countdown and prioritizes work accordingly, which is useful for long-running agentic loops where you want graceful completion rather than abrupt cutoff when token limits are hit.

What got worse

Three things to understand before flipping the switch.

Multi-source web research regressed. This is the clearest regression in 4.7. When the agent browses, reads several pages, and synthesizes findings into a report, 4.7 runs redundant queries, source attribution accuracy drops, contradiction detection weakens, and citation specificity falls. Opus 4.6 outperforms 4.7 on this specific workflow. If multi-source web research synthesis is your primary use case, this upgrade is not ready for you yet.

Instruction following got more literal. Opus 4.7 follows instructions precisely rather than inferring what you meant. Where Opus 4.6 would sometimes generalize an instruction from one context to a related one, 4.7 doesn’t. Prompts that relied on 4.6’s loose interpretation will produce narrower, more literal outputs. This is not uniformly bad, but it will break workflows where you relied on the model making reasonable inferences. You’ll need to rewrite those prompts to be explicit.

The new tokenizer adds up to 35% more tokens. Opus 4.7 ships with a new tokenizer that can produce 1x to 1.35x as many tokens for the same input text, depending on content type. The rate card didn’t change. Your invoice might. If you’re running high-volume pipelines, measure your actual token counts on 4.7 before assuming your costs stayed flat.

The four breaking API changes

These require code changes, not just prompt updates.

budget_tokens is gone. The old way to control extended thinking depth (thinking: {type: "enabled", budget_tokens: N}) is removed entirely. The new approach is adaptive thinking: pass thinking: {type: "adaptive"} and the model decides how much to reason based on the task. You lose the ability to set an explicit thinking token cap.

thinking.display default changed. It used to default to "summarized", meaning you'd get a thinking summary in the response. In 4.7 it defaults to "omitted", meaning block.thinking comes back as an empty string unless you explicitly setthinking.display: "summarized" or "full". Any code that reads thinking blocks without checking for empty strings will silently produce blank output.

Temperature, top_p, and top_k now return 400. These parameters no longer work at non-default values on Opus 4.7. If your code sets any of them, the API returns a 400 error. Remove them from your request or update your error handling.

Prefilling assistant messages is blocked. Passing a partial assistant message to steer the output format returns a 400 error. Use system prompt instructions or output_config.format instead.

Decision framework

Here’s where to land based on what you’re actually building.

Switch now if:

• Your primary use case is coding, code review, or software engineering tasks
• You run multi-step agentic workflows and care about completion rate on long tasks
• Your workflows involve image analysis or high-resolution document processing
• You’re building new pipelines without legacy 4.6 prompts to migrate

Switch after testing if:

• You have production prompts tuned to Opus 4.6’s behavior: test your prompts against 4.7’s more literal interpretation before deploying
• You’re cost-sensitive and running high-volume workloads: measure actual token counts on 4.7 first, since the tokenizer change can add 35% to the bill
• You use any of the four broken API features: adaptive thinking migration is the most complex; plan the refactor before switching

Hold or keep 4.6 if:

• Your core workflow is multi-source web research synthesis: this is the one area where 4.6 outperforms 4.7 as of this writing

For most people, the upgrade is worth it. The 2x agentic efficiency alone justifies it for anyone running agent loops. But “most people” is not “everyone,” and the tokenizer cost increase plus the four breaking changes mean this is a planned migration, not a one-line model ID swap.

The practical migration path: use model ID claude-opus-4-7-20260416, raise max_tokens to give headroom for the tokenizer change, and start with effort: "xhigh" for agentic tasks. If using xhigh or max effort, start max_tokens at 64k minimum.

Where Agent Teams fit

Agent Teams were introduced with Opus 4.6 in February 2026 and Opus 4.7 inherits them. If you’ve been using the orchestrator-worker pattern, 4.7 is a clear upgrade as the orchestrator model.

The 2x reduction in LLM calls matters most here: the orchestrator on Opus 4.7 completes planning and synthesis passes faster with fewer total invocations. The proactive output verification also reduces review cycles between orchestrator and worker.

For a detailed look at how to structure these workflows, the previous article in this series covers multi-agent orchestration with Opus 4.7 Agent Teams in full.

The real upgrade story

“Same price, better model” is the headline. The more accurate description is: significantly better for coding and agentic work, with a meaningful regression on web research synthesis, and up to 35% more expensive in practice due to the tokenizer change.

That’s not a reason to skip the upgrade. It’s a reason to test on your actual use cases first, update your API code for the four breaking changes, and recheck your cost estimates before you go to production.

The model is better where it counts for most builders. Just don’t assume the upgrade is frictionless.

Sources

[1] Claude Opus 4.7 release announcement: Anthropic. April 16, 2026. SWE-bench Verified 87.6%, vision accuracy, Agent Teams inheritance, Project Glasswing.

[2] What’s new in Claude Opus 4.7: Anthropic Platform Docs. xhigh effort level, task budgets beta, image resolution specs, breaking changes.

[3] Claude Opus 4.7 vs 4.6 comparison: MindStudio. SWE-bench Pro/Verified/CursorBench numbers, 7.1 vs 16.3 LLM calls, p50 latency.

[4] Claude Opus 4.7 review (regressions): MindStudio. Web research regression detail: redundant queries, source attribution, contradiction detection.

[5] Claude Opus 4.7 pricing and tokenizer impact: Finout. 1x–1.35x token inflation from new tokenizer.

[6] Claude Opus 4.7 benchmark analysis: The AI Corner. Vision accuracy 54.5% to 98.5%, CursorBench breakdown.

[7] Claude Opus 4.7 migration guide: Anthropic Platform Docs. Four breaking API changes with migration paths.

[8] Effort parameter documentation: Anthropic Platform Docs. Five effort levels, xhigh recommendation for coding and agentic tasks.

[9] Effort level cost-performance analysis: Claudefa.st. xhigh at ~100k tokens = ~71%; max at ~200k tokens = ~74.5%.

[10] Claude Opus 4.6 Agent Teams launch: TechCrunch. February 2026. Agent Teams introduced with 4.6, not 4.7.

Originally published at koriigami.com.

Stop typing the same instructions. Build a skill once, use it forever.

You’ve opened a new Claude Code session for the third time this week. You type the same block of instructions you always type: “Review this PR diff. Check for missing error handling, performance issues, and anything that breaks our naming conventions. Format your response as a structured list by category.”

Claude does a great job. Just like it did on Monday. And last Thursday.

The problem isn’t that Claude can’t do this. The problem is that you have to remember to ask it the right way, every single time.

Skills are the fix.

What Skills Actually Are

A Claude Code skill is a saved, reusable prompt — packaged as a file that becomes a slash command.

When you type /review-pr, Claude doesn't just know what to do. It loads a set of instructions you wrote once, and follows them exactly, every time. You get consistent behavior without re-explaining yourself.

The mental model: a skill is a CLAUDE.md file for a specific task. Your CLAUDE.md sets project-wide context. A skill sets task-specific context, on demand.

As of January 2026, Claude Code merged its slash commands system directly into skills [2]. These used to be two separate mechanisms — now they’re the same thing. If you write a skill, you automatically get a /slash-command from it. One system, zero duplication.

If you’ve been using Claude Code for a while, you may have had project-specific slash commands in .claude/commands/. Those still work — they're now treated as project-scoped skills. No migration needed.

Your First Skill: /daily-standup in 10 Minutes

Here’s one worth building immediately: a skill that reads your git history from the past 24 hours and formats a standup update.

Step 1: Create the skill file

mkdir -p ~/.claude/skills/daily-standup
touch ~/.claude/skills/daily-standup/SKILL.md

Step 2: Write the SKILL.md

---
name: daily-standup
description: "Summarize yesterday's git commits and generate a standup update"
version: 1
---
​
# Daily Standup Skill
​
Run the following command and analyze the output:
​
```bash
git log --since="24 hours ago" --oneline --author="$(git config user.name)"

Then generate a standup update in this format:

What I did yesterday:

• [bullet per meaningful commit or theme, grouped logically]

What I’m working on today:

• [leave this blank — the user will fill it in]

Blockers:

• None (unless the user mentions one)

Keep it concise. No filler. Each bullet should be something a teammate actually cares about.

Step 3: Use it

/daily-standup

That’s it. Claude reads your git log, analyzes the commits, and produces a standup-ready summary. You fill in “today” and you’re done in 30 seconds.

Global vs. Project Skills: Where to Store Them

Claude Code has two places for skills [1]:

Global: `~/.claude/skills/`

Stored in your home directory. Available in every project, every session. Use this for workflows that belong to *you* — not to a specific codebase.

~/.claude/skills/
├── daily-standup/SKILL.md
├── review-pr/SKILL.md
├── explain-error/SKILL.md
└── commit/SKILL.md

Project: `.claude/skills/` or `.claude/commands/`

Stored inside a repository. Only available when working in that project. Use this for conventions that are specific to a codebase — like a skill that enforces your team’s exact PR review checklist. Both paths work; `.claude/skills/` is the newer recommended location, `.claude/commands/` is supported for backward compatibility.

.claude/skills/
├── review-api-changes/SKILL.md
└── check-design-tokens/SKILL.md

Precedence rule:

If you have a global skill and a project skill with the same `name`, the project skill wins. This lets you override global defaults per-repo [5].

A practical split: put personal productivity skills (standup, commit messages, error explanations) globally. Put repo-specific review checklists, deploy procedures, and naming convention checks in the project.

The SKILL.md Format

Every skill is a single `SKILL.md` file with a YAML frontmatter block followed by the instruction body [4]:

name: review-pr
description: "Review a pull request diff for error handling, performance, and naming conventions"
version: 1
---

PR Review Skill

Fetch the current PR diff using:

gh pr diff

Review the changes and produce a structured report with these sections:

Error Handling: Missing try/catch, unhandled promise rejections, no null checks on external data

Performance: N+1 queries, unnecessary re-renders, large bundle imports

Naming Conventions: CamelCase for variables, PascalCase for components, kebab-case for files

Summary: one paragraph with the overall assessment and whether this is ready to merge

Be specific. Cite line numbers where relevant.

The key fields in frontmatter:

1. `name` becomes your `/slash-command`. Keep it short and a single hyphenated string.
2. `description` used for auto-discovery (more on this below). Write it as a sentence describing what the skill does, not how.
3. `version` is optional. Increment when you make significant changes. Useful for skills you share or install from the marketplace; fine to omit for personal skills.

The instruction body is everything after the frontmatter. Write it in imperative voice: “Fetch the diff”, “Review the changes”, “Generate a report.” Be explicit about what format you want Claude to produce.

Auto-Discovery: Skills That Suggest Themselves

Here’s a feature that earns its keep after you’ve built a few skills.

Claude Code reads the `description` field of every installed skill at session start. When your message matches a skill’s description semantically, Claude will proactively suggest using it — even if you didn’t type the slash command [1].

So if you have a `/review-pr` skill installed with description `”Review a pull request diff…”` and you say “can you check this PR for issues?”, Claude might respond: “It looks like your `/review-pr` skill is designed for this, want me to use that?”

This is why the description field matters more than it looks. Write it as a clear, intent-describing sentence. “Review a pull request diff for error handling and naming issues” will match more reliably than “PR review helper”.

Auto-discovery is most useful once you have 5+ skills installed. At that point, you stop needing to remember slash commands , Claude surfaces the right tool based on what you’re asking.

The EXTEND.md Pattern: Personalizable Skills

If you install a skill from the marketplace (or share one with your team), you probably don’t want to edit the base SKILL.md directly, that would break updates.

Instead, many skills support an `EXTEND.md` preferences file. You place it alongside the skill:

~/.claude/skills/review-pr/
├── SKILL.md        ← the base skill (don't edit this)
└── EXTEND.md       ← your personal overrides

The EXTEND.md typically uses YAML frontmatter for structured preferences:

---
version: 1
preferred_output: markdown-table
severity_levels: [critical, warning, suggestion]
ignore_patterns:
  - "*.test.ts"
  - "*.stories.tsx"
---

When Claude runs the skill, it reads EXTEND.md first and merges your preferences into the execution. You get a shared base behavior with personal customization layered on top; no forks, no merge conflicts [3].

Five Skills Worth Building

If you’re a product designer or AI-first developer, these five cover most of the repetitive work:

/commit: Reads your staged diff, generates a conventional commit message in the right format, asks for confirmation before running git commit. Saves the 2–3 minutes of writing a good message under pressure.

/review-pr: Fetches the PR diff via gh pr diff, checks against your team's standards, outputs a structured review. Useful as a self-review before requesting a real reviewer.

/explain-error: Paste an error message, stack trace, or unexpected output. Claude identifies the root cause, explains what went wrong, and suggests a fix. Works well for unfamiliar errors in codebases you didn't write.

/write-component: For design-to-code work: describe a UI component, reference a Figma node if available, specify your stack (React + Tailwind, etc.). Claude generates the component following your existing conventions, using CLAUDE.md as context.

/check-accessibility: Run against a component or page file. Checks for missing aria labels, keyboard navigation issues, color contrast violations, and focus management problems. A good pre-publish checklist.

Sharing Skills and the Marketplace

Skills are just files. Sharing them is as simple as committing them to a public repo.

The baoyu-skills marketplace (github.com/JimLiu/baoyu-skills) is the largest community collection [3]. It includes content skills, AI generation skills, and development workflow tools, most of which install via Claude Code’s plugin system with a single command.

If you build a skill that works well, consider publishing it. The format is simple enough that a SKILL.md + README is a complete, installable skill package.

For team use: store project skills in .claude/skills/ in your repo. Any developer who clones the repo gets the skills automatically. No separate install step, no docs to maintain — the skill is the docs.

Getting Started Checklist

Work through these in order. Each one builds on the last.

• Identify your top 3 most-repeated Claude Code prompts (the ones you type from memory)
• Create ~/.claude/skills/ if it doesn't exist
• Pick the simplest repeated prompt and convert it to a SKILL.md
• Test the skill with /your-skill-name in a real session
• Refine the instruction body based on the output — be more specific about format
• Build skill #2 and #3
• Add EXTEND.md support to any skill you might share or reuse across projects
• Browse the baoyu-skills marketplace for skills you don’t need to build yourself

Start with one. The skill-building habit develops once you’ve felt the difference between typing a skill name and re-explaining a workflow from scratch.

You’ve Completed the Claude Code Power User Series

If you’ve followed this series from Part 1:

• You’ve set up a CLAUDE.md that gives Claude context about your project before you type a word.
• You’ve configured hooks that make your best practices automatic, formatting, notifications, safety checks.
• You’ve run parallel agents on a codebase without file conflicts using git worktrees.
• And now you have skills that save your best prompts and turn them into repeatable workflows.

These four things compound. A CLAUDE.md + hooks + parallel agents + custom skills is a development environment that gets noticeably more productive the more you use it — because the overhead of working with Claude goes down while the quality of its output goes up.

The rest is iteration. Build skills for the tasks that still feel slow. Update your CLAUDE.md when you learn something new about your codebase. Add hooks for the checks that matter most. The system improves as you use it.

Sources

[1] Claude Code documentation : Skills and slash commands: https://code.claude.com/docs/en/skills

[2] Anthropic changelog, January 2026 : Slash commands merged into Skills system

[3] baoyu-skills marketplace : github.com/JimLiu/baoyu-skills

[4] Claude Code documentation : SKILL.md format and frontmatter reference: https://code.claude.com/docs/en/skills#skillmd-format

[5] Claude Code documentation: Global vs project skill precedence: https://code.claude.com/docs/en/skills#skill-locations

This is Part 4 of the Claude Code Power User series. End of Series

Stop waiting for one agent to finish before starting the next.

You ask Claude Code to fix a bug. It works. While it’s doing that, you have three other tasks sitting in a queue - a feature to add, a test suite to expand, a refactor to finish. You wait. Claude commits the bug fix. You paste the next task. You wait again.

This is the single-agent bottleneck. It’s the most common way people use Claude Code, and the most wasteful. Those tasks aren’t dependent on each other. There’s no reason they need to run one after another.

Claude Code now has a native answer to this: git worktrees plus parallel agent sessions. You can run two, three, four Claude Code agents simultaneously on the same repo; each one working on a separate branch, completely isolated, without stepping on each other’s work.

This is Part 3 of the Claude Code Power User series. We covered CLAUDE.md configuration in Part 1 and hooks in Part 2. Here we get into multi-agent architecture: the setup that Boris Cherny, Claude Code’s creator, has described as central to his own development process. [1]

The Core Concept: One Repo, Many Working Trees

Before worktrees, running parallel Claude Code agents on the same repo meant either cloning the repo multiple times (messy, disk-heavy, diverges from your remotes) or accepting that agents would clobber each other’s file changes mid-task.

Git worktrees solve this cleanly. A worktree is an isolated checkout of your repository at a specific branch. The repo’s Git history and object store are shared (you don’t duplicate the whole repo), but each worktree has its own working directory and branch pointer. Changes in one worktree don’t appear in another until you merge. [2]

Claude Code’s --worktree flag automates the full setup. Under the hood it runs git worktree add, creates a new branch, sets up an isolated session directory under .claude/worktrees/, and launches a Claude Code session scoped to that context. When the session closes, teardown is handled for you.

The mental model is this: each agent lives in its own lane. Same highway (the repo), different lanes (worktrees). They never collide unless you explicitly merge them.

Setting Up Your First Worktree

Starting a parallel agent session takes one command:

claude --worktree feature-auth

That’s it. Claude Code will:

1. Create a new branch worktree-feature-auth
2. Set up an isolated working directory at .claude/worktrees/feature-auth/
3. Inherit your project’s CLAUDE.md configuration
4. Launch a Claude Code session scoped to that worktree

In a second terminal window (or a tmux pane), you can start a second agent immediately:

claude --worktree fix-payment-bug

Now you have two Claude Code agents running simultaneously. One is building the auth feature on worktree-feature-auth. The other is diagnosing and fixing the payment bug on worktree-fix-payment-bug. Neither knows the other exists. Neither touches the other's files.

What Gets Inherited, What Doesn’t

Each worktree session inherits:

• CLAUDE.md from the project root (unless you place an overriding CLAUDE.md in the worktree directory)
• Hooks configuration (each agent runs its own hook context. The same hooks apply, but they fire independently per session)
• .claude/settings.json defaults

Each worktree session does NOT share:

• Conversation history with other sessions
• File changes (by design this is the whole point)
• In-progress tool calls or task state

Real-World Parallel Workflows

Theory is easy. Here’s how parallel worktrees look in practice.

1. Bug Fix + Feature Development

The classic case. You have a production bug that needs fixing; nothing too complex, but it needs focus. You also have a feature sprint you’re supposed to be making progress on.

# Terminal 1 — fix the bug
claude --worktree fix-invoice-rounding
# Prompt: "The invoice total rounds incorrectly for non-USD currencies. Investigate
# src/billing/invoice.ts, fix the rounding logic, and add a regression test."
​
# Terminal 2 — keep building
claude --worktree feat-invoice-templates
# Prompt: "Add a template selection step to the invoice creation flow.
# Reference the existing flow in src/billing/create-invoice.tsx."

Both run. Both commit to their own branches. You review the bug fix first (it’s smaller), merge it, then review the feature PR with fresh context.

2. Implementation + Test Coverage

You want Claude to write a new module AND ensure it’s fully tested, but you don’t want to wait for implementation to finish before testing starts. If the implementation is well-specced, an agent can start writing tests against the spec while another builds the module.

# Terminal 1 — build the module
claude --worktree feat-rate-limiter
# Prompt: "Implement a token-bucket rate limiter in src/lib/rate-limiter.ts
# per the spec in docs/specs/rate-limiter.md"
​
# Terminal 2 — write tests against the spec
claude --worktree test-rate-limiter
# Prompt: "Write a comprehensive test suite for the rate limiter spec in
# docs/specs/rate-limiter.md. Target file: src/lib/rate-limiter.test.ts.
# The implementation is being written in parallel — test to the spec, not the code."

When both finish, you merge the implementation branch, then apply the test branch on top. Some tests may need minor adjustments where the spec was ambiguous , but you’ve saved the sequential wait.

3. Refactor + New Feature (Parallel, Non-Overlapping Files)

When you know two tasks touch separate parts of the codebase, there’s no reason to run them sequentially. A refactor of your API layer doesn’t block a UI component update.

# Terminal 1 — refactor
claude --worktree refactor-api-layer
# Prompt: "Refactor src/api/ to use the new response wrapper pattern
# from src/lib/api-response.ts. No new features — only structural changes."
​
# Terminal 2 — new component
claude --worktree feat-settings-panel
# Prompt: "Build the new settings panel component per the mockup in
# design/settings-panel.png. Output to src/components/SettingsPanel.tsx."

4. Research + Writing (Non-Code Work)

Parallel worktrees aren’t just for engineers. If you’re using Claude Code for content work, like writing this article series you can run a research agent and a drafting agent simultaneously.

# Terminal 1 — research agent
claude --worktree research-topic-x
# Prompt: "Research [topic]. Summarize key findings into research/RESEARCH-topic-x.md"
​
# Terminal 2 — drafting agent
claude --worktree draft-article-y
# Prompt: "Draft the article outline and opening section for article-y.md,
# using existing research in research/RESEARCH-article-y.md"

5. Code Quality: Three-Agent Parallel Review

The parallel agent pattern I use day-to-day isn’t worktrees. It’s parallel subagent dispatch. My /simplify command runs three Claude agents simultaneously against the same codebase: one scans for reuse opportunities, one reviews code quality, one audits efficiency. All three run in parallel and report back their findings before any changes are applied.

No worktrees needed, because all three agents are read-only. No file conflicts are possible when you’re only reading. This is the lighter end of the parallel-agent spectrum: read-parallel analysis rather than write-isolated development.

The pattern generalises. Any task where multiple agents examine the same code without modifying it (security audits, dependency scans, performance profiling) can run this way. You get the speed of parallelism without the branch management overhead of worktrees.

# /simplify dispatches three agents in a single command — you don't manage them individually
/simplify
​
# Under the hood, three agents run simultaneously:
# Agent 1: scan for reuse opportunities and duplicate code
# Agent 2: review code quality (naming, structure, complexity)
# Agent 3: audit efficiency (unnecessary computations, redundant state)

Parallel agents exist on a spectrum. Use worktrees when agents need to make changes that can’t step on each other. Use subagent dispatch when agents are reading the same codebase from different angles.

Agent Teams: The Next Level

Worktrees give you parallel isolation. Agent Teams give you coordination.

Introduced in Claude Opus 4.6 (February 2026), Agent Teams let you define a structured team of Claude instances that operate collaboratively. One instance acts as orchestrator: it breaks down tasks, assigns subtasks to workers, and reviews their results before anything is committed. [3]

The distinction matters:

• Subagents (the original model) are quick, focused workers that complete a task and report back. They’re fire-and-forget. No awareness of other agents.
• Agent Teams are teammates. They share findings, coordinate on approach, and the orchestrator maintains a global view of what’s been done and what remains.

Enabling Agent Teams

Agent Teams is currently experimental. Enable it with an environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or persist it in .claude/settings.json so it applies to every session in the project:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Once enabled, there’s no CLI flag or config file to write. You activate a team through a natural language prompt; Claude handles the orchestration:

Create an agent team to add a CSV export feature to the reports page.
Break it into implementation, tests, and review. Run implementation
and tests in parallel, then review both before committing.

The orchestrator agent takes over: it reads the codebase, plans the work, assigns tasks to worker agents running in parallel worktrees, and reviews the combined output before producing a final diff. Task state is stored locally at ~/.claude/tasks/{team-name}/.

The orchestrator runs on Opus (currently 4.7), which costs roughly 5× what Sonnet costs per token. A typical team session — orchestrator plus two Sonnet workers at around 1K tokens each — runs $0.03–0.15. That’s negligible. It compounds in longer sessions with multiple review cycles. For tasks you can complete in a single 10–15 minute Sonnet session, Agent Teams adds overhead without proportionate benefit. Reserve it for complex multi-file work where the orchestrator’s coordination and review step actually changes the outcome.

When NOT to Parallelize

Parallel agents are powerful. They’re also genuinely wrong for some situations.

When tasks share files. If two agents are likely to edit the same file, a shared utility, a config, a type definition; you’ll face a merge conflict that can be harder to resolve than just doing the work sequentially. Worktrees isolate branches, not merge conflicts. You still have to reconcile divergent changes when you merge.

When context dependency is high. If Task B depends on understanding what Task A produced, running them in parallel means Task B operates on assumptions. This works fine with a spec (the test-against-spec pattern above), but if the spec is the output of Task A, you need to wait.

When you’re debugging something subtle. Debugging requires close attention. Running a parallel agent session in the background while you’re debugging pulls your focus. The benefit of parallelism is that you’re doing something useful while Claude works — not that you’re watching two Claude sessions simultaneously.

When merge overhead exceeds the time saved. For small tasks (under 10–15 minutes of Claude work), the overhead of creating worktrees, managing two terminal sessions, and reviewing two separate branches may cost more time than just doing them sequentially. Reserve parallel workflows for tasks substantial enough to justify the coordination cost.

Getting Started Checklist

Use this as a quick reference the first time you set up a parallel workflow:

[ ] Identify two tasks that are independent (no shared files, no output dependency)
[ ] Open two terminal windows or tmux panes
[ ] Run: claude --worktree <name-1> in the first window
[ ] Run: claude --worktree <name-2> in the second window
[ ] Give each agent its task prompt
[ ] Let both run — check in periodically but don't hover
[ ] Review the smaller/faster task first
[ ] Merge the first branch, then review and merge the second
[ ] Clean up worktrees: git worktree remove .claude/worktrees/<name>

For teams experimenting with Agent Teams:

[ ] Add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to .claude/settings.json env block
[ ] Start with a small, well-scoped task to test team coordination
[ ] Describe the task and team structure in natural language — Claude handles orchestration
[ ] Audit the final diff carefully — multi-agent output needs more review scrutiny, not less

The Mindset Shift

The biggest barrier to parallel agents isn’t technical — it’s the instinct to work serially.

Most developers have an internal queue: finish one thing, start the next. That works well when you’re the one writing the code. It’s unnecessarily limiting when Claude Code is doing the work and your job is to direct and review.

Think about how you’d delegate to a team. You don’t assign one task, wait for it to finish, then assign the next. You map out the work, identify what can run in parallel, assign it, and follow up at natural review points.

That’s the frame for parallel Claude Code agents. You’re not a developer who uses Claude as a tool. You’re a technical lead directing a team of agents — and the quality of your direction, not the speed of your typing, is what limits throughput.

Sources

[1] Boris Cherny on parallel multi-agent development workflows — cited from public statements describing his personal Claude Code usage. Cherny is the creator of Claude Code at Anthropic.

[2] Git worktree documentation — git worktree add allows multiple working trees attached to the same repository. Each worktree has its own checkout, branch pointer, and working directory. Official reference: https://git-scm.com/docs/git-worktree

[3] Claude Opus 4.6 Agent Teams — introduced February 6, 2026. Enables orchestrator + worker agent coordination with shared context and autonomous task assignment. Reference: Anthropic release notes for Claude Opus 4.6.

This is Part 3 of the Claude Code Power User series.

Originally published at https://koriigami.com on April 24, 2026.

This guide covers the setup, custom event tracking, and common gotchas.

Why @next/third-parties

Before this package, the typical approach was:

// The old way - manual Script component
import Script from 'next/script';
 
export default function Layout({ children }) {
  return (
    <html>
      <head>
        <Script
          src={`https://www.googletagmanager.com/gtag/js?id=G-XXXXX`}
          strategy="afterInteractive"
        />
        <Script id="gtag-init" strategy="afterInteractive">
          {`
            window.dataLayer = window.dataLayer || [];
            function gtag(){dataLayer.push(arguments);}
            gtag('js', new Date());
            gtag('config', 'G-XXXXX');
          `}
        </Script>
      </head>
      <body>{children}</body>
    </html>
  );
}

This works, but you’re managing script loading yourself. The @next/third-parties package wraps this in a component that:

• Handles script loading timing correctly
• Avoids hydration mismatches
• Provides a typed sendGAEvent function for custom events
• Follows Next.js best practices for third-party scripts

Installation

npm install @next/third-parties

That’s it. No additional dependencies.

Basic setup

Add the GoogleAnalytics component to your root layout:

// app/layout.tsx
import { GoogleAnalytics } from '@next/third-parties/google';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <GoogleAnalytics gaId="G-XXXXXXXXXX" />
      </body>
    </html>
  );
}

Replace G-XXXXXXXXXX with your measurement ID from Google Analytics.

Finding your measurement ID

1. Go to Google Analytics
2. Admin (gear icon) → Data Streams
3. Click your web stream
4. Copy the Measurement ID (starts with G-)

Environment variable setup

Hardcoding the GA ID works, but using an environment variable is cleaner:

# .env.local
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

// app/layout.tsx
import { GoogleAnalytics } from '@next/third-parties/google';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const gaId = process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID;
 
  return (
    <html lang="en">
      <body>
        {children}
        {gaId && <GoogleAnalytics gaId={gaId} />}
      </body>
    </html>
  );
}

The NEXT_PUBLIC_ prefix is required because the GA ID needs to be available client-side.

Production-only tracking

You probably don’t want analytics running during development. Add an environment check:

// app/layout.tsx
import { GoogleAnalytics } from '@next/third-parties/google';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const gaId = process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID;
  const isProduction = process.env.NODE_ENV === 'production';
 
  return (
    <html lang="en">
      <body>
        {children}
        {gaId && isProduction && <GoogleAnalytics gaId={gaId} />}
      </body>
    </html>
  );
}

Now analytics only loads in production builds.

Pageview tracking

Good news: you don’t need to do anything special. Google Analytics automatically tracks pageviews when the browser history state changes. This means client-side navigations between Next.js routes send pageview data without configuration.

For this to work, make sure “Enhanced Measurement” is enabled in your GA property:

1. Admin → Data Streams → Select your stream
2. Enhanced measurement → Toggle on
3. Ensure “Page changes based on browser history events” is checked

Custom event tracking

Pageviews are automatic, but you’ll want to track specific user actions: button clicks, form submissions, purchases.

The sendGAEvent function

Import sendGAEvent from @next/third-parties/google:

'use client';
 
import { sendGAEvent } from '@next/third-parties/google';
 
export function BookingButton() {
  const handleClick = () => {
    sendGAEvent('event', 'booking_started', {
      service_type: 'consultation',
    });
 
    // Continue with booking logic...
  };
 
  return (
    <button onClick={handleClick}>
      Book Now
    </button>
  );
}

The function signature is:

sendGAEvent(command: string, eventName: string, eventParams?: object)

• command is usually 'event'
• eventName is your custom event name
• eventParams is an optional object with additional data

Common event patterns

Button clicks:

sendGAEvent('event', 'cta_clicked', {
  button_text: 'Get Started',
  page_location: window.location.pathname,
});

Form submissions:

const handleSubmit = async (formData: FormData) => {
  const result = await submitForm(formData);
 
  if (result.success) {
    sendGAEvent('event', 'form_submitted', {
      form_name: 'contact',
    });
  }
};

External link clicks:

<a
  href="https://external-site.com"
  target="_blank"
  onClick={() => sendGAEvent('event', 'external_link_clicked', {
    destination: 'https://external-site.com',
  })}
>
  Visit Partner Site
</a>

Service selection:

const handleServiceSelect = (serviceName: string) => {
  sendGAEvent('event', 'service_selected', {
    service_name: serviceName,
  });
 
  // Navigate to booking page...
};

Creating a tracking utility

For larger apps, wrap sendGAEvent in a utility file:

// lib/analytics.ts
'use client';
 
import { sendGAEvent } from '@next/third-parties/google';
 
export const analytics = {
  trackEvent: (eventName: string, params?: Record<string, string | number>) => {
    sendGAEvent('event', eventName, params);
  },
 
  trackPageView: (pagePath: string) => {
    sendGAEvent('event', 'page_view', {
      page_path: pagePath,
    });
  },
 
  trackButtonClick: (buttonName: string, location?: string) => {
    sendGAEvent('event', 'button_clicked', {
      button_name: buttonName,
      page_location: location || window.location.pathname,
    });
  },
 
  trackFormSubmission: (formName: string, success: boolean) => {
    sendGAEvent('event', 'form_submission', {
      form_name: formName,
      success: success ? 'true' : 'false',
    });
  },
 
  trackBookingStarted: (serviceType: string) => {
    sendGAEvent('event', 'booking_started', {
      service_type: serviceType,
    });
  },
 
  trackBookingCompleted: (serviceType: string, bookingId: string) => {
    sendGAEvent('event', 'booking_completed', {
      service_type: serviceType,
      booking_id: bookingId,
    });
  },
};

Usage:

'use client';
 
import { analytics } from '@/lib/analytics';
 
export function ContactForm() {
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
 
    const result = await submitContactForm(formData);
    analytics.trackFormSubmission('contact', result.success);
  };
 
  return <form onSubmit={handleSubmit}>...</form>;
}

Event naming conventions

Google Analytics has some rules for event names:

• Must be 40 characters or fewer
• Must start with a letter
• Can only contain letters, numbers, and underscores
• Case-sensitive (button_clicked and Button_Clicked are different events)

Use snake_case for consistency:

// Good
sendGAEvent('event', 'booking_completed', { ... });
sendGAEvent('event', 'contact_form_submitted', { ... });
 
// Avoid
sendGAEvent('event', 'Booking Completed', { ... });
sendGAEvent('event', 'contact-form-submitted', { ... });

Debugging analytics

Check if the script loads

Open browser DevTools → Network tab → Filter by “google”. You should see requests to googletagmanager.com.

Use GA Debug mode

Install the Google Analytics Debugger Chrome extension. It logs all GA events to the console.

Real-time reports

In Google Analytics:

1. Reports → Realtime
2. Open your site in another tab
3. Watch events appear as they happen

Events show up in realtime within seconds. Standard reports can take 24–48 hours to populate.

Verify the tag is detected

1. Admin → Data Streams → Select your stream
2. Click “Test your connection”
3. Enter your URL
4. Should show “Your Google tag was correctly detected”

Common issues

Events not showing up

Check the environment: Events only fire in production if you added the isProduction check. For testing, temporarily remove that condition.

Wrong measurement ID: Double-check the ID. Typos are common.

Ad blockers: Many ad blockers prevent GA scripts from loading. Test in incognito mode with extensions disabled.

Duplicate pageviews

If you’re seeing duplicate pageviews, you might have both the old Script method and the new GoogleAnalytics component. Use one or the other, not both.

Events not attached to the right page

When tracking events, the page URL is automatically captured. If you need to override it:

sendGAEvent('event', 'custom_event', {
  page_location: '/custom/path',
  page_title: 'Custom Page Title',
});

sendGAEvent is undefined

Make sure:

1. The GoogleAnalytics component is in your layout
2. You’re calling sendGAEvent in a client component ('use client')
3. The component has mounted (events won’t fire during SSR)

TypeScript types

The sendGAEvent function accepts any object for eventParams. For type safety, define your event types:

// lib/analytics.ts
 
type EventParams = {
  button_clicked: {
    button_name: string;
    page_location: string;
  };
  form_submitted: {
    form_name: string;
    success: boolean;
  };
  booking_completed: {
    service_type: string;
    booking_id: string;
  };
};
 
export function trackEvent<T extends keyof EventParams>(
  eventName: T,
  params: EventParams[T]
) {
  sendGAEvent('event', eventName, params);
}

Now you get autocomplete and type checking:

// Type-safe
trackEvent('button_clicked', { button_name: 'cta', page_location: '/home' });
 
// Type error - missing page_location
trackEvent('button_clicked', { button_name: 'cta' });

Privacy considerations

Cookie consent

Depending on your audience, you may need cookie consent before loading GA. Common pattern:

'use client';
 
import { GoogleAnalytics } from '@next/third-parties/google';
import { useState, useEffect } from 'react';
 
export function AnalyticsWrapper() {
  const [consentGiven, setConsentGiven] = useState(false);
 
  useEffect(() => {
    const consent = localStorage.getItem('analytics_consent');
    if (consent === 'true') {
      setConsentGiven(true);
    }
  }, []);
 
  if (!consentGiven) return null;
 
  return <GoogleAnalytics gaId={process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID!} />;
}

Then conditionally render in layout:

<body>
  {children}
  <AnalyticsWrapper />
  <CookieBanner onAccept={() => { /* trigger re-render */ }} />
</body>

IP anonymization

GA4 anonymizes IP addresses by default. You don’t need to configure anything extra.

File structure

app/
  layout.tsx          # GoogleAnalytics component
lib/
  analytics.ts        # Optional: tracking utility functions
.env.local              # NEXT_PUBLIC_GOOGLE_ANALYTICS_ID

Key takeaways

Use @next/third-parties instead of manual script injection. Pageviews are tracked automatically with Enhanced Measurement. Use sendGAEvent for custom events in client components. Add a NODE_ENV === 'production' check to avoid dev tracking.

The @next/third-parties package removes the friction from GA setup. Add the component, configure your measurement ID, and you're tracking. Custom events are one function call. No manual script management, no hydration issues.

Going further: Looker Studio for client reporting

Setting up GA4 on your site is one thing. When a client asks “how is my website performing?” — they don’t want to navigate Google Analytics. They want a clean dashboard with a date picker and the five numbers they actually care about.

Looker Studio connects directly to GA4 and lets you build that dashboard without any code.

Connecting GA4 to Looker Studio

1. Go to lookerstudio.google.com and create a new report
2. Click Add data → search for Google Analytics
3. Select your GA4 property → click Add

That’s the connection. All GA4 data is now available as dimensions and metrics in Looker Studio.

What to include in the dashboard

I built this for a client who is a mental well-being life coach — she publishes articles frequently and drives traffic from LinkedIn and Facebook. She needed answers to specific questions, not a full analytics education.

Overview

• Date range control — lets her toggle between last 7, 30, or a custom range herself
• Scorecards: total sessions, total users, average engagement time

Audience

• Device category breakdown (desktop / mobile / tablet)
• Top countries by sessions
• Top browsers and operating systems

Traffic sources

• Session source / medium table — shows whether traffic is coming from LinkedIn, Facebook, direct, organic search, or email
• With UTM parameters on her links, this table shows exactly which post or campaign drove each visit

Content performance

• Top viewed pages
• Top 5 articles by sessions — essential if your client publishes content regularly and wants to know what resonates

UTM tracking for content creators

UTM parameters are the difference between “traffic came from Facebook” and “traffic came from that specific post you published last Tuesday.”

Add them to every link your client shares:

https://example.com/blog/article-slug?utm_source=facebook&utm_medium=social&utm_campaign=march-content

The Session Source / Medium chart in Looker Studio will label them exactly as you’ve set. Your client sees at a glance which content channel is actually driving visitors — not just which platform.

When Looker Studio is worth setting up

Not every client needs a custom dashboard — GA4’s built-in reports are sufficient for most. Looker Studio earns its setup time when:

• Your client doesn’t want to learn the GA4 interface
• Multiple stakeholders need to view the same data
• The client publishes content regularly and wants to track performance systematically
• You want to combine GA4 with other data sources (Google Search Console, Sheets)

Originally published at https://www.koriigami.com on April 22, 2026.