AGENTS.md · Commands · Skills · Plugins · MCP: the five layers for configuring an AI coding agent, from a single instruction file to live external tools.
Before any configuration
System prompts, your AGENTS.md, skills. Everything this session teaches lives in this layer or feeds it.
File edits, shell, and (through MCP) anything you connect: ticket systems, databases, browsers.
The finite window holding the conversation, files, and tool results. Every extension you add pays rent here.
No magic anywhere in this session: just these three, configured deliberately.
One file at repo root. The agent's baseline knowledge of your codebase.
15 minThe / menu: built-ins worth knowing, and what custom commands really are.
15 minProcedural knowledge that loads only when the task matches. The core of the day.
30 minVersioned, namespaced distribution, to your team and from the marketplaces.
20 minLive tools and data from outside the agent: tickets, databases, browsers.
30 minFiles first, connections last: each layer builds on the one before it. Break after Module 03.
Ground rule
Every module ends with a checkpoint from the Lab Workbook. The workbook is self-contained: anyone who misses the session can work through it alone.
Vendor note: the reference tool is Claude Code. AGENTS.md, Agent Skills, and MCP are open standards, so those modules transfer to Cursor, Codex, Gemini CLI, OpenCode, and others.
Verify now
The agent starts every session knowing nothing about your repository. One markdown file fixes that: the cheapest, highest-leverage configuration you will write today.
One file, read automatically
A README explains the project to humans. AGENTS.md tells an agent how to operate: exact commands, conventions, prohibitions, and where the deeper docs live.
It loads on every session, which is both its power and its budget. Every line pays context rent whether the session needs it or not.
Cross-vendor: most agents read AGENTS.md natively. Claude Code reads CLAUDE.md; keep AGENTS.md canonical and symlink.
The shape that works
Build, test, and lint commands, exactly as your team runs them. House conventions an outsider couldn't guess. Internal libraries to prefer. Directories never to touch. Pointers to deeper docs.
Anything the model already knows (what a PDF is, how git works). Prose essays. And procedures: the moment a section becomes step-by-step instructions for an occasional task, it belongs in a skill (Module 03).
Monorepos: nested AGENTS.md per package; the closest file wins. Keep the root file global, push specifics down.
Everything behind the / key is one of two things: a built-in command, or a skill. Fluency with the first; a door into the second.
Shipped with the tool: /clear, /permissions, /mcp, /config. They manage the session and the machinery around it. You can't write these, but the next slide's working set is worth memorizing.
Everything else: every custom command you'll ever write, plus the bundled ones like /debug and /batch. Extensible, shareable, and the subject of Module 03.
Type / and read your own list; entries vary by platform and plan. MCP servers add a third source later: /mcp__server__prompt.
| Command | What it does |
|---|---|
| /context | Colored-grid view of what's filling the window. Run it after every module today. |
| /permissions | Allow / ask / deny rules for tools: the guardrail surface. |
| /mcp | Server status, tool counts, OAuth. Module 05 home base. |
| /compact | Summarize the conversation to free space; keeps the thread. |
| /clear | Wipe and start fresh; cheaper when you don't need the thread. |
| Command | What it does |
|---|---|
| /rewind | Roll back conversation and/or code. The undo most people don't know exists. |
| /skills | List every skill currently available. Module 03 home base. |
| /model | Switch model; configure effort. |
| /doctor | Diagnose installation and settings. First stop when anything misbehaves. |
| …plus /init and /memory from Module 01. | |
The pivot to Module 03
Drop a folder in .claude/skills/, restart, and /standup exists. The !`…` line runs before the model reads the prompt: its output is injected into the text.
The legacy form (a flat file in .claude/commands/) still works, but skills win name conflicts and are the form to write going forward.
.claude/skills/standup/SKILL.md
Procedural knowledge the agent loads only when the task matches. The open standard, the anatomy, and how to write skills that actually work. The core of the session.
Why skills exist
AGENTS.md loads always.
A skill loads when relevant;
until then it costs ~100 tokens.
At startup the agent sees only each skill's name and description. The body (up to ~5k tokens of instructions, plus unlimited referenced files) enters context only when a task matches. That asymmetry is the entire design.
At startup, only the name and description of every installed skill load. The description is the trigger: it decides everything downstream.
always in contextA task matches the description; the full SKILL.md body enters context. Keep it under 500 lines: concise steps, one worked example.
on matchThe agent follows the instructions, running bundled scripts and reading referenced files only when the work calls for them.
scripts/ · references/For big skills, push depth down a stage: move detail into references/ and tell the agent when to read each file: "Read references/api-errors.md if the API returns non-200."
.claude/skills/money-handling/SKILL.md
"Helps with PDFs" never triggers. "Extracts text and tables from PDF files — use when working with PDF documents" does.
| Frontmatter | Who can invoke | Use for |
|---|---|---|
| (default) | You and the model | Most skills: conventions, procedures, reference knowledge. |
| disable-model-invocation: true | Only you, via /name | Side effects: /deploy, /commit, /release. The model never decides to run these on its own. |
| user-invocable: false | Only the model | Background knowledge, hidden from the / menu entirely. |
Claude Code extensions, same file: $ARGUMENTS and named arguments, !`command` pre-injection, context: fork to run in a subagent, allowed-tools to pre-approve tools while the skill is active.
Pushed through managed settings. Wins all name conflicts; the org's rules are not optional.
admin-controlledYour habits, every project you open. Yours beats the repo's on a name collision.
~/.claude/skills/Committed to version control, so the whole team gets it on clone. Where team conventions live.
.claude/skills/Edits to an existing SKILL.md apply live in the session. New top-level folders need a restart. Plugin skills (Module 04) are namespaced: they never collide.
Bundled scripts
A script that asks "Continue? [y/N]" hangs forever, because agents can't answer prompts. Design accordingly:
The skills directory
skills.sh is the public directory: trending lists, official collections, and security audits. Worth knowing: skill-creator (Anthropic's skill for writing skills) and the document skills (pdf, docx, xlsx, pptx).
A skill in .claude/skills/ serves one repo. A plugin packages skills (plus hooks, subagents, and MCP configs) into a versioned, namespaced unit you can install anywhere.
Personal or project-specific. Short names like /standup. Commit the folder and same-repo teammates already share it. Quick experiments live and die here, cheaply.
Deliberate releases via semver, or every commit ships, SHA-versioned. Names become /team-standards:standup: no collisions with anyone else's /standup. Installable by people who've never seen your repo.
The conversion is mechanical: a manifest file plus your existing folders. The decision is organizational: who else needs this, and how do they get updates?
team-standards/
The #1 structural mistake, per the official docs: putting component directories inside .claude-plugin/. Only the manifest lives there.
name is the namespace. version pins releases: omit it and the git SHA versions every commit.
Paths inside the plugin: always ${CLAUDE_PLUGIN_ROOT}, because the install directory moves on update.
pyright, gopls, rust-analyzer, typescript… The agent sees type errors after every edit (no compile step) and navigates by symbol instead of grep.
binary on PATH requiredGitHub, GitLab, Linear, Sentry, Figma, Supabase: plugins that bundle a pre-configured MCP server. The cleanest way to hand a team a connection.
bundled .mcp.jsoncommit-commands, pr-review-toolkit, and code-review (the replacement for the deprecated /review built-in).
skills + agentsBrowse with /plugin. Install scopes: user (all your projects) · project (committed, team-shared) · local (this repo, just you) · managed (pushed by admins). Team catalogs: /plugin marketplace add acme-org/claude-plugins.
| Component | File | Adds |
|---|---|---|
| Skills | skills/*/SKILL.md | Everything from Module 03, namespaced. |
| Hooks | hooks/hooks.json | Checks at ~30 lifecycle events; PreToolUse can block a call before it runs. |
| Subagents | agents/*.md | Specialized agents with their own tools, model, and isolation. |
| MCP servers | .mcp.json | Connections that start when the plugin is enabled (Module 05). |
| LSP | .lsp.json | Live diagnostics and code navigation. |
| PATH tools | bin/ | Executables available to the agent's shell while enabled. |
Today you ship skills. The rest are pointers; each is a tutorial of its own.
Everything so far has been files the agent reads. MCP adds connections: typed tools and live data from the systems around your code.
When to reach for MCP
The moment you catch yourself
copy-pasting from another tool
into the chat.
Tickets, error traces, database rows, design specs: if you ferry it by hand, a server can hand it to the agent directly. Skills carry knowledge; MCP carries capability. They compose: this module ends with skills that build MCP servers.
Remote · HTTP
Cloud services: docs, Sentry, GitHub, Notion. Zero install; OAuth where needed.
Local · stdio
Local processes: browsers, filesystems, databases. The missing -- is the #1 add-time failure.
Verify with claude mcp list: five statuses from ✓ Connected to ⏸ Pending approval. First tool use prompts for permission; calls are labeled with the server name. SSE transport is deprecated.
| Scope | Lives in | Who sees it |
|---|---|---|
| local | ~/.claude.json (per-project) | You, this project. The default. |
| project | .mcp.json at repo root | The whole team; committed, approval-gated. |
| user | ~/.claude.json (top level) | You, every project. |
Scope is fixed at add time: changing it means remove and re-add with --scope.
.mcp.json · no secrets, ever
${VAR} expansion keeps keys out of version control; teammates get an approval prompt before anything launches.
Tool Search keeps the bill down by default: full schemas load on demand, not at startup. Output is capped (MAX_MCP_OUTPUT_TOKENS, default 25k). The cheapest mitigation: claude mcp remove for servers you stopped using.
A server that fetches external content (web pages, tickets, emails) can carry prompt injection in that content. Treat server trust like dependency trust: prefer official and curated servers for anything that touches credentials.
The standards compose
Three composing skills interview you (what it connects to, who uses it, how it authenticates) and then scaffold the right deployment shape: remote HTTP for cloud APIs, a bundle for local machine access, stdio for prototypes.
Watch-only today
The registry holds metadata, not code: your package still lives on npm, with an mcpName field tying the two together.
| "I want the agent to…" | Layer | Why |
|---|---|---|
| know our build commands | AGENTS.md | Every session needs it. |
| follow our review checklist on request | Skill | Some sessions need it; pay on use. |
| never run deploys on its own | Skill · user-only | disable-model-invocation, plus /permissions. |
| give the whole org our conventions | Plugin | Versioned, namespaced, installable. |
| read tickets without copy-paste | MCP server | Capability, not knowledge. |
Three steps that compound
In that order, on one real repo, this week. The AGENTS.md takes twenty minutes. The skill comes from your last code review. The server comes from your copy-paste audit.
Commands, skills, plugins, MCP: the reference for everything in Modules 02–05.
also: an MCP server of itselfThe Agent Skills spec, best practices, and script guidance.
open standardCommunity skills with install counts and security audits.
npx skills add <owner/repo>The MCP spec, registry, and server-building guides.
spec · registry · sdksThe cross-vendor instruction-file convention from Module 01.
CLAUDE.md → AGENTS.mdAll five tutorials with checkpoints, exercises, and troubleshooting; self-contained for anyone who missed today.
share freely