How to Turn Coding Agent Sessions Into Reusable Skills (2027)

Last Tuesday your coding agent got the rate limiter right. Today a teammate asks for the same thing on a new endpoint, and the agent starts from zero. It reaches for an in-memory counter, opens a fresh Redis connection, fails CI twice, and spends tokens relearning decisions your team already made. This guide shows how to turn coding agent sessions into reusable skills with a text editor, a git repo, and a spreadsheet. Once the manual version stops scaling, tools like ZeroShot can automate extraction, tracking, and enforcement. Start with the method, because the method is what makes any tool useful.

What Is a Reusable Coding Agent Skill?

A reusable coding agent skill is a short, versioned instruction file, usually named SKILL.md, that captures a decision a human or agent already made. It says when the skill applies, which steps to follow, what a correct example looks like, and which checks prove the result is right. The agent loads it so it does not have to work the decision out again in every session.

Turning a session into a skill means extracting that decision and its conventions from a session that worked. It does not mean saving the transcript. The transcript is the path you took. The skill is where you ended up and why.

Skills are easy to confuse with the other files that shape agent behavior. The differences matter because each one has a different cost and scope:

• A prompt is one-off. It lives in a single session and disappears with it.
• AGENTS.md or a rules file (CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md) is always-on, repo-wide context, read at the start of every session.
• A skill is scoped. Under the Agent Skills open standard, only its name and description load at startup. The full body loads only when the task matches its trigger. This is called progressive disclosure.
• Documentation is written for humans to read. A skill is written for an agent to execute, with file paths, commands, and pass/fail checks.

Anthropic introduced Agent Skills in October 2025 and published the format as an open specification at agentskills.io in December 2025. Several other agent vendors, including OpenAI Codex and GitHub Copilot, have since announced SKILL.md support. Check each vendor's current docs, because support changes quickly.

A session is a one-time cost; a skill is the receipt that keeps you from paying it twice.

Why Agent Knowledge Doesn't Carry Over (What Breaks)

Every coding agent session starts from zero, because the context window holds only this session's discoveries and drops them when the session ends. The agent that finally learned your team uses lib/redis.ts forgets it the moment you close the terminal. The next session, on your machine or a teammate's, rediscovers it or doesn't.

Five failure modes show up on almost every team that runs agents daily:

1. Convention drift. The agent picks a different HTTP client, error format, or logging library than the one your team standardized on. The code works. It just isn't yours.
2. Repeated wrong turns. The same plausible-but-wrong approach, such as an in-memory counter in a multi-instance service, gets tried, fails CI, and gets tried again next week.
3. Tribal knowledge stays tribal. The engineer who steered the agent to the right answer has the fix in their head and their session history. Nobody else does.
4. Review load shifts to humans. Reviewers leave the same comment ("use our Redis client, not a new connection") on PR after PR.
5. Context bloat from overcorrection. Teams react by pasting everything into one giant rules file. That dilutes the instructions that matter, invites "lost in the middle" failures and context rot, and costs tokens on every call.

The 2025 Stack Overflow Developer Survey found that 66% of developers name "AI solutions that are almost right, but not quite" as their biggest frustration, and 45% say debugging AI-generated code takes more time. "Almost right" is convention drift: correct-looking code that uses the wrong client or the wrong keying strategy.

A bigger model does not fix this. The missing input is your team's decisions, not general capability. Google Cloud's 2025 DORA report on AI-assisted development reaches a similar conclusion: AI amplifies a team's existing strengths and weaknesses. Codified decisions are a strength worth amplifying.

The Method: Session-to-Skill in 7 Steps (No Tools Required)

The session-to-skill method has seven steps: Spot, Extract, Write, Store, Review, Measure, Retire. Everything below works with a text editor, a git repo, and a spreadsheet. No vendor, plugin, or account required.

Step 1: Spot a solved problem worth reusing

Not every session deserves a skill. Make one only when all four of these are true:

• The problem has recurred, or will recur, at least twice.
• The right answer depends on a team-specific convention the model can't infer from public code.
• Getting it wrong cost real retries, review comments, or failed CI.
• The solution is merged and passing.

Skip one-offs. Skip anything a linter or type-checker can already enforce.

Signal	Make a skill	Don't
Reviewer left the same comment 3+ times	Yes
Formatting or import order		Use a linter, not a skill
Choice between two valid libraries the team already decided	Yes
Non-obvious infra constraint (multi-instance, auth, compliance)	Yes
Generic language knowledge		Neither: the model already knows it
A one-time migration script		Archive the PR instead

Step 2: Extract the decision, not the transcript

Reread the session and the merged PR, then answer five questions in writing:

1. What was decided?
2. Which alternatives were rejected, and why?
3. Which existing files, clients, or helpers must be reused?
4. What are the non-obvious constraints (multi-instance, auth, compliance, latency)?
5. How do we know it worked: which tests, which commands?

Throw away the dead ends unless one is a trap worth warning about. Question 2 is the most valuable. Models default to the most statistically common solution, so a written list of rejected approaches counters the model's prior directly.

Step 3: Write the SKILL.md

Use this structure:

• YAML frontmatter: name (max 64 characters, lowercase letters, numbers, and hyphens) and description (max 1,024 characters). Write the description as a trigger, in the third person, with keywords the task is likely to contain. For example: "Use when adding rate limiting to any public API route."
• When to use / when not to use.
• Steps: numbered, imperative, referencing real file paths.
• Example: a minimal snippet or a link to the reference PR.
• Checks: exact commands and expected results, e.g. "npm test -- ratelimit passes; response includes Retry-After."
• Anti-patterns: the rejected approaches and why they fail.

Keep it to about one screen. Anthropic's authoring guidance caps the SKILL.md body around 500 lines and recommends moving extra material into a references/ folder, but single-decision skills should be far shorter. Agents skim long skills too.

Step 4: Store it in the repo, next to the code

Use a predictable directory. For Claude Code, project skills live in .claude/skills/<name>/SKILL.md and are shared with everyone who clones the repo. Personal skills live in ~/.claude/skills/. Then add a one-line pointer in AGENTS.md, such as "Before rate-limiting work, read .claude/skills/api-rate-limiting/SKILL.md", so agents that don't auto-discover skills still find them. Git gives you history and reviewable diffs for free.

Step 5: Review it like code

Open a PR for the skill itself. The engineer who solved the original problem should approve it, and the skill needs a named owner (a CODEOWNERS entry for .claude/skills/ works well). Then test it once: start a fresh agent session on a similar task with the skill present, and confirm the agent follows it. If it doesn't load, the description is the usual culprit.

Step 6: Measure reuse and savings in a spreadsheet

Impressions are unreliable. In METR's July 2025 randomized trial, experienced open-source developers were 19% slower with early-2025 AI tools on their own repos, yet afterwards believed they had been about 20% faster. Measure instead. Track these columns:

• Skill name, owner, created date, last validated date
• Times used (from session logs or PR descriptions)
• First-try CI pass (Y/N)
• Retries before vs. after
• Tokens or cost per task before vs. after (from your provider's usage dashboard or the agent's cost output)
• Review comments on that topic before vs. after

Ask engineers to write skill: <name> in PR descriptions so usage is countable with a simple search.

Step 7: Retire or refresh stale skills

Stale agent skills are dangerous because agents follow them confidently. Refresh or delete a skill when:

• A referenced file or library was removed.
• The convention changed.
• The skill went unused for a full quarter.
• An agent followed it and still failed.

Delete rather than let it rot. A wrong skill is worse than no skill.

Cadence: spend 15 minutes writing a skill after any session that took more than one retry to land, and hold a 30-minute monthly skill review using the spreadsheet.

Worked Example: Rate-Limiting Middleware, Solved Once, Reused Forever

The following is an illustrative scenario with plausible, internally consistent numbers. It shows how the method works. It is not a claimed result.

The original session

An engineer asks an agent to add rate limiting to a public API. The first attempt uses an in-memory counter. It passes locally but fails the integration test that runs two service instances. The second attempt opens a new Redis connection instead of using the shared client in lib/redis.ts, and the reviewer flags it. The third attempt keys limits by IP, but the product requires per-API-key limits. Attempt four lands after about 3 hours and roughly 400,000 tokens.

The decisions extracted

Answering the five Step 2 questions produces this:

• Token-bucket algorithm, backed by the existing shared Redis client.
• Key by API key. Fall back to IP only on unauthenticated routes.
• Default 100 requests/minute, overridable per route.
• Return HTTP 429 (defined in RFC 6585) with a Retry-After header.
• Exempt /healthz.
• Rejected: in-memory counters, because the service runs multiple instances.

The resulting SKILL.md

---
name: api-rate-limiting
description: Adds per-API-key rate limiting to public HTTP routes using the shared Redis client and token-bucket middleware. Use when adding, changing, or debugging rate limits, throttling, or 429 responses on any public API or webhook route.
---

## When to use
- Adding or changing rate limits on a public API or webhook route
## When not to use
- Internal service-to-service calls (limited at the gateway)

## Steps
1. Import the shared client from lib/redis.ts. Never open a new Redis connection.
2. Apply rateLimit() from src/middleware/rateLimit.ts to the route.
3. Key by req.apiKey.id; fall back to req.ip only on unauthenticated routes.
4. Use 100 req/min unless route config sets rateLimit.perMinute.
5. On limit, return 429 with Retry-After (seconds). Exempt /healthz.

## Example
import { redis } from "@/lib/redis";
import { rateLimit } from "@/middleware/rateLimit";

router.post(
  "/webhooks/billing",
  rateLimit({ redis, perMinute: 100,
    key: (req) => req.apiKey?.id ?? req.ip }),
  billingWebhookHandler
);

## Checks
- npm test -- ratelimit.multi-instance passes
- curl: 101st request within 60s returns 429 with Retry-After

## Anti-patterns
- In-memory counters: break across multiple instances.
- New Redis connections: exhaust the pool. Use lib/redis.ts.
- IP-only keys on authenticated routes: violates per-key product limits.

The reuse

Two weeks later, a different engineer asks an agent to rate-limit a new webhook endpoint. The description matches "webhook" and "rate limit," so the agent loads the skill. It uses the shared client, keys by API key, returns 429 with Retry-After, and passes CI on the first try in one short session.

Metric	Original session	With skill
Retries before green CI	3	0
Wall-clock time	~3 hours	~20 minutes
Review comments on rate limiting	4	0
Tokens per task	~400k	~40k

The token drop is large because exploration and failed CI loops are where the token cost actually lives. Each failed attempt means reading more files, rerunning tests, parsing failure output, and rewriting code. A skill removes the search, not just the typing.

The lesson: the value came from the rejected alternatives and the multi-instance constraint. A transcript buries those under hours of dead ends. A skill puts them in the first screen the agent reads.

Common Mistakes When Turning Sessions Into Skills

Most failed skills fail for one of eight predictable reasons, and nearly all of them come down to missing judgment or missing upkeep.

• Saving transcripts as skills. Agents re-read the dead ends and sometimes repeat them. You pay tokens to load a story when you needed a rule.
• Vague trigger descriptions. "Backend best practices" either never matches a task or matches every task. Either way, the skill fails at its one job.
• No checks section. Without a verifiable definition of done, the agent can follow every step and still ship something wrong.
• Codifying a bad decision. A skill extracted from a session that merely passed CI spreads a mediocre pattern quickly. No tool fixes this. Only human review of the decision does.
• Contradictory skills. Two skills disagree on error format and the agent picks one. You need an owner and a periodic audit, with or without tooling.
• Skills for linter jobs. Formatting and import rules belong in deterministic tooling, not probabilistic instructions. Skills explain the why and how. CI proves the what.
• No owner, no retirement. Skills point at deleted files, and agents follow the stale instructions confidently.
• Writing skills nobody measures. Without usage counts, you can't tell a load-bearing skill from dead weight.

When the Manual Method Stops Scaling (and the Tools That Help)

Hand-written skills work well for a handful, but past roughly 20 skills, or once several engineers run agents daily, the spreadsheet falls behind. Nobody knows which skills exist, whether agents loaded them, or which ones are stale. Extraction becomes the bottleneck too: good sessions end, and nobody has 15 minutes to write them up.

Watch for these symptoms:

• Duplicate skills covering the same decision.
• skill: <name> tags missing from most PRs.
• Reviewers still leaving the comments skills were meant to prevent.
• No one can answer "did the agent use the skill on this PR?"

Option	Extracts skills from sessions	Tracks usage and staleness	Enforces skills on PRs	Cost
ZeroShot (recommended)	Yes, from sessions and PR reviews	Yes, plus daily Slack report	Yes, blocks PRs that skip skills	Free Mac app and CLI; team plans via demo
Native agent features (SKILL.md, rules files, AGENTS.md)	No, written by hand	No	No	Free
DIY CI scripts	No	Partial (what you build)	Partial (tag checks)	Free, but you own the maintenance

1. ZeroShot

ZeroShot is covered in its own section below. In short: it automates the Spot, Extract, Measure, and Retire steps across every coding agent your team runs.

2. Native agent features

Your agent's own skills or rules mechanism, such as Claude Code skills in .claude/skills/ or Cursor's glob-scoped .mdc rules, plus an AGENTS.md file. These are free and enough for small skill sets. They give you no usage tracking and no enforcement.

3. DIY in CI

A script that checks PR descriptions for skill tags, or validates that every path referenced in a SKILL.md still exists. It's cheap to write. It's also maintenance you own forever.

Tooling automates steps 1, 2, 6, and 7 of the method. It does not replace the human judgment in step 2 about whether a decision is any good.

ZeroShot: Session-to-Skill Without the Spreadsheet

ZeroShot is agent session monitoring for the coding agents a team runs: it turns sessions and PR reviews into reusable skills, hands off any session to any teammate, and enforces skills on every PR. In the rate-limiting example above, ZeroShot would extract the skill from the original engineer's session and surface it to the next agent that touches a webhook, without anyone setting aside 15 minutes to write it up.

What it does, mapped to the method:

• Spot and Extract: skills that write themselves, drawn from successful sessions and recurring PR review comments.
• Review: PR reviews that cite your team's conventions, so the reviewer comment points at the skill instead of repeating it.
• Enforce: block PRs that skip the skills that apply to them, which answers "did the agent use the skill?" directly.
• Measure: visibility into every session, plus a daily Slack report on what shipped overnight, time and money saved, and which skills to sharpen.
• Handoff: pass any in-progress agent session to any teammate, with its context intact.

ZeroShot works with every coding agent. Skills are open-source files you keep in your repo, and it can run fully locally so code never leaves your machine. It is SOC 2 Type II, GDPR, and HIPAA compliant. Install the free Mac app (no account needed), the Intel Mac build, or the CLI:

curl -fsSL https://tryzeroshot.com/install.sh | sh

ZeroShot reports that pilot teams over a 90-day window saw 3.7x faster delivery, 90% less wasted token spend per task, and 67% less PR review time. Given the METR findings above, check those numbers against your own spreadsheet. The Step 6 columns make that comparison easy.

FAQ: Reusable Skills for Coding Agents

What is a SKILL.md file?

A SKILL.md is a markdown file with YAML frontmatter. It requires a name (max 64 characters, lowercase letters, numbers, and hyphens) and a trigger-style description (max 1,024 characters). It tells a coding agent when to apply a specific procedure, the steps to follow, an example, and checks that verify the result. It lives in its own folder, optionally with scripts/, references/, and assets/ subfolders.

What's the difference between AGENTS.md and a skill?

AGENTS.md is always-on, repo-wide context read in every session. A skill is scoped to one task, and only its name and description load until its trigger matches. Use AGENTS.md for universal facts (build commands, hard constraints, a pointer to skills) and skills for task-specific procedures.

Should I save the full agent transcript as a skill?

No. Transcripts contain dead ends that agents may imitate, they cost tokens to read, and they bury the actual decision. Extract the decision, the conventions, the rejected alternatives and the reasons for rejecting them, the files to reuse, and the verification commands.

Where do Claude Code skills live?

Project skills go in .claude/skills/<skill-name>/SKILL.md, committed to git so the whole team gets them. Personal skills go in ~/.claude/skills/. Plugins can also bundle skills. Claude Code discovers them automatically and loads the full body when the description matches the task.

Do skills work with agents other than Claude Code?

Increasingly, yes. Anthropic published Agent Skills as an open spec in December 2025, and OpenAI Codex, GitHub Copilot, and several other agents announced SKILL.md support. For agents without native support, add a pointer in AGENTS.md (for example, "Before rate-limiting work, read skills/rate-limiting/SKILL.md"). Check current vendor docs, because support changes often.

How many skills should a team have?

Start with the 3 to 5 problems that caused the most retries or repeated review comments. Manual management works up to roughly 20 skills. Beyond that, you need automated tracking of usage and staleness.

How do I know a skill is working?

Compare first-try CI pass rate, retries, tokens per task, and review comments on that topic before and after the skill exists. Test with a fresh agent session on a similar task.

When should I delete a skill?

Delete it when it references code that no longer exists, when the convention has changed, when it has gone unused for a quarter, or when agents follow it and still fail. A wrong skill is worse than no skill.

Sources and Further Reading

• AGENTS.md open format for agent instructions: https://agents.md
• Anthropic's public skills repository (SKILL.md examples and format): https://github.com/anthropics/skills
• Token bucket algorithm, background for the worked example: https://en.wikipedia.org/wiki/Token_bucket
• RFC 6585, which defines HTTP 429 Too Many Requests: https://datatracker.ietf.org/doc/html/rfc6585
• Stack Overflow Developer Survey 2025 (AI tool usage and trust)
• METR, "Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity" (July 2025)
• Google Cloud DORA, 2025 State of AI-Assisted Software Development
• ZeroShot: https://tryzeroshot.com

Stop raw-dogging agents

Your agents already solved most of the problems they'll hit this week. The decisions are sitting in last month's sessions and PR reviews. ZeroShot turns those sessions into skills, checks that every PR follows them, and shows you which skills are saving time and which need work. It's free on Mac, needs no account, and can run entirely on your machine.

Download ZeroShot free