What if You're Using your Coding Agents Naked?

2026-07-05

It's 2026, and most developers using Claude Code, Codex CLI, Cursor, or Gemini CLI are having the same conversation with their agent, every single day.

They say things like "Use our error handling pattern." "Remember, we use Route Handlers, not the old pages/api style." "No, don't add a test for that, we don't test config files." "Validate with zod before touching the DB, always."

Every session starts from zero. The agent is smart - genuinely capable of writing full features, running tests, and shipping code, but it has no memory of your team's conventions unless you retype them. If you multiply that by every developer on the team, every new session, every day, and you've got a lot of wasted breath going into a very expensive autocomplete.

This is the single biggest way people are underusing coding agents right now: they're treating a highly capable, instructable system like a stateless chatbot, and re-explaining the same tribal knowledge over and over instead of teaching it once.

The fix has a name, and it's been quietly becoming the standard way to solve this since Anthropic released it as an open format in December 2025: Agent Skills.

What a Skill actually is

A Skill is nothing exotic. It's a folder with a file called SKILL.md inside it, plus, optionally - some reference docs, scripts, or templates. Think of it as an onboarding packet you'd hand a new hire on their first day: here's how we structure routes, here's our validation convention, here's the script that checks your work before you commit.

skill-name/
├── SKILL.md          ← required
├── references/        ← optional, extra docs
├── scripts/            ← optional, deterministic checks
└── templates/          ← optional, boilerplate to start from

The SKILL.md file has two parts: a short YAML header (name and description) and a markdown body with the actual instructions. That's the whole spec.

Why this actually works: progressive disclosure

The reason Skills scale instead of just becoming another bloated prompt is a loading trick called progressive disclosure. It happens in three stages, and each one only costs context when it's genuinely needed:

  1. Startup - the agent reads just the name + description of every installed skill. Tiny. Always loaded.
  2. Match - when you send a request, the agent compares it against those descriptions. If one fits, it reads the full SKILL.md body.
  3. Deep dive - if the task needs it, the agent opens bundled reference files or runs a script. If it doesn't need form-filling instructions, for example, it never opens forms.md.

So a Skill can carry a huge amount of institutional knowledge - an entire API reference, a full test-writing playbook - without ever taxing the context window unless the current task actually calls for that specific slice of it.

A concrete example

Say your team keeps writing inconsistent Next.js API routes. Instead of re-explaining the convention in every chat, you write it once:

.claude/skills/nextjs-conventions/
├── SKILL.md
├── reference/
│   ├── api-routes.md
│   ├── server-components.md
│   └── data-fetching.md
├── scripts/
│   └── check-route-naming.sh
└── templates/
    ├── route.template.ts
    └── page.template.tsx

The SKILL.md frontmatter might read:

---
name: nextjs-conventions
description: Use when creating or modifying pages, API routes, or data-fetching
  logic in this Next.js App Router project. Do NOT use for styling-only changes.
---

Ask for "an API route for user signup," and the agent matches the description, loads the relevant reference doc, pulls the route template, writes the handler, and runs the naming-check script - all without touching the unrelated server-components.md file, because that wasn't part of the task.

That's the whole value proposition: write your conventions once, and the agent reaches for exactly the slice it needs, exactly when it needs it.

It's not a Claude-only trick anymore

This is the part a lot of people still don't realize. Skills started as an Anthropic format, but it was published as an open standard in December 2025, and adoption moved fast. By 2026 it's supported across 30+ platforms - Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, Roo Code, Goose, and more.

Because a skill is just a folder and a markdown file - filesystem-based, not tied to any one API - the same skill works across tools with zero modification. The only thing that changes is where the folder lives:

| Agent | Personal skills | Project skills | |---|---|---| | Claude Code | ~/.claude/skills/ | .claude/skills/ | | Codex CLI | ~/.codex/skills/ | .codex/skills/ | | Gemini CLI | ~/.gemini/skills/ | .gemini/skills/ | | Cursor | - | .cursor/skills/ |

Write one skill, commit it to your repo, and every developer on the team gets consistent behavior regardless of which agent they personally prefer.

A couple of honest caveats: vendor-specific extensions (Claude Code's subagent forking, Codex's own metadata fields) don't transfer between tools, and matching "aggressiveness" can vary slightly agent to agent. But a skill written in the plain, generic core format works essentially everywhere.

Practical tricks worth stealing

Symlink instead of copy-pasting. If you use more than one agent, don't maintain duplicate folders - point them all at one source of truth:

ln -s ~/.claude/skills/ ~/.codex/skills
ln -s ~/.claude/skills/ ~/.gemini/skills

Push deterministic steps into scripts, not prose. Markdown instructions get interpreted, which is fine for most guidance but risky for validation that has to be exact every time - a missing field, a malformed name. Bundle a small Python or Bash script for those checks instead. It returns pass/fail with no room for the agent to "interpret" its way around a real problem.

Write descriptions with negative triggers. A vague description gets a skill firing on tasks it shouldn't touch. Be explicit about what it's not for: "Do NOT use for styling-only changes or non-Next.js files." This single habit fixes more false-trigger problems than almost anything else.

Build from observed failures, not guesses. The best skills get written after watching an agent actually struggle on a real task - forgetting to filter test accounts from a query, using the wrong routing pattern - not from imagining what it might need in advance.

Keep SKILL.md lean, push detail into references/. If the core file is getting long, split out edge cases and full API docs into separate files the agent only opens on demand. Your everyday instructions stay fast to load; the rarely-needed detail stays available without costing anything most of the time.

The bigger point

None of this is about a fancier prompt. It's a shift in how people relate to their agent at all: from re-explaining context every session to writing it down once, committing it, and letting every developer - on every agent - inherit the same expertise automatically.

If you're still typing out your team's conventions from scratch in 2026, that's the actual inefficiency. Not the model. Not the tool. The missing folder.