Skip to main content

Skills, AGENTS.md, and CLAUDE.md

info

This content was developed with AI assistance and is regularly reviewed for accuracy.

Snapshot: October 2026. Model names, prices, and product features change monthly; What's New in AI is the maintained chronology.

Every agent you use needs two kinds of standing knowledge: the rules of the place it is working in, and the know-how for specific jobs. In 2026 both have open, cross-vendor formats. Project rules go in an instruction file (AGENTS.md, or CLAUDE.md for Claude Code). Reusable know-how goes in a skill, a folder with a SKILL.md file. This page shows you how each works, when to use which, and how to write ones that travel between tools.

Learning focus​

  • Explain the difference between always-on instructions and on-demand skills
  • Write a working SKILL.md that follows the Agent Skills open standard
  • Set up AGENTS.md and CLAUDE.md without duplicating rules
  • Install and share skills safely

Two kinds of standing knowledge​

Think of a new colleague joining your team. On day one you hand them the house rules: where things live, how to run the build, what never to do. Later, when they first write a quarterly report, you give them the report checklist. They do not need the checklist every day; they need it when the report is due.

Agents work the same way. Instruction files are the house rules. The agent reads them at the start of every session, so they should be short and always relevant. Skills are the checklists. The agent sees only each skill's name and one-line description until a task calls for it, then loads the full instructions, examples, and scripts. That on-demand loading is the reason skills scale: you can install fifty of them without filling the context window, the working memory the model reads on every turn.

Instruction file (AGENTS.md, CLAUDE.md)Skill (SKILL.md folder)
LoadsEvery sessionOnly when the task matches its description
HoldsProject rules, commands, conventionsStep-by-step know-how for one job, plus optional scripts and examples
ScopeOne project or one personPortable across projects and agents
Typical sizeTens of linesAnything from a page to a folder of resources

The Agent Skills standard​

Anthropic introduced Agent Skills in Claude Code in October 2025 and released the format as an open standard on December 18, 2025, with the specification published at agentskills.io. By March 2026, OpenAI, Microsoft, JetBrains, Cursor, Google's Gemini CLI, Block's Goose, and at least 25 other agent products had shipped compatible implementations (reported). OpenAI maintains its own public skills repository. On October 22, 2026 Anthropic donated the standard to the Agentic AI Foundation, the Linux Foundation body that also governs MCP and AGENTS.md, and said more than 70 agent platforms, including ChatGPT and Cursor, had adopted it. In practice this means a skill you write once can run in Claude, Claude Code, Codex, and other compatible agents without rewriting.

The format is deliberately small. A skill is a folder containing a SKILL.md file. The file starts with frontmatter, and only two fields are required: name and description. Everything after the frontmatter is ordinary markdown instructions. The folder can also hold supporting files the instructions refer to.

weekly-report/
SKILL.md instructions and frontmatter
template.md the report layout to fill in
examples/ one or two finished reports
scripts/ optional helpers the agent can run

The description does the most work, because it is what the agent reads when deciding whether to load the skill. Write it as "what it does, and when to use it."

Write your first skill​

Pick a task you repeat at least weekly and already do the same way each time. Meeting notes, a status report, or a code-review checklist are good first choices. Then follow four steps.

1. Create the folder. For Claude Code, personal skills live in ~/.claude/skills/ and project skills in .claude/skills/ inside the repository. Other agents use their own skills folder; the file format is the same.

2. Write the SKILL.md.

---
name: meeting-notes
description: Turns a meeting transcript into structured notes with decisions and action items. Use when the user shares a transcript or recording summary and asks for notes or follow-ups.
---

# Meeting notes

## Steps
1. Identify the date, participants, and purpose.
2. List decisions made, one line each.
3. Build an action-item table: owner, task, due date. If an owner or date is missing, write "unassigned" rather than guessing.
4. Summarize open questions separately from decisions.
5. Draft a short follow-up email to participants.

## Output
- Three-bullet summary at the top
- Decisions, then the action-item table, then open questions
- Follow-up email draft last

## Check before finishing
- Every action item appears in the transcript
- No names or dates are invented

3. Test it. In Claude Code, invoke it directly with /meeting-notes, or give the agent a transcript and see whether it loads the skill on its own. If it does not, the description is too vague; add the words a user would actually say.

4. Refine from failures. Run it on three real inputs. Every time the output is wrong, add a line to the steps or the check section that would have prevented it. That habit is the start of an eval, covered in Evals for Agents.

What makes a skill good​

The best skills are narrow. "Sales email reply" beats "business helper," because the agent can match it to a task and you can tell whether it worked. Include one or two worked examples when the format matters, since examples communicate layout better than descriptions. Write the edge cases down ("if no budget is given, ask") instead of hoping the model guesses. End with a short check section so the agent verifies its own output before handing it back.

Skills can also bundle scripts. A data skill might include a Python script that validates a CSV before analysis; the instructions tell the agent when to run it. Scripts make skills more reliable, and they also make them code you are choosing to run, which matters for the safety section below.

Skills in the apps, not just the terminal​

You do not need a terminal to use skills. Skills are a listed feature on Claude's paid plans, and skills you add in the Claude app sync into Claude Code. Claude's agent mode also uses skills and plugins for work such as brand voice, legal, and finance reviews. Other assistants offer their own containers for reusable instructions: Gemini has Gems, and ChatGPT moved organizations from Custom GPTs to Workspace Agents in 2026. Individual ChatGPT accounts can no longer create new Custom GPTs as of August 2026, though existing ones still work.

If you are on a personal plan and want reusable behavior today, the portable choice is a SKILL.md folder. A project with custom instructions is the right choice when the reusable part is background context rather than a procedure; Customize: Projects, Skills, RAG, Fine-Tuning helps you choose.

AGENTS.md and CLAUDE.md​

AGENTS.md is a plain markdown file at the root of a repository that tells any coding agent how to work there. It was contributed by OpenAI to the Agentic AI Foundation, the same body that governs MCP and Agent Skills, and it has been adopted by over 60,000 open-source projects and supported by GitHub Copilot, Cursor, Gemini CLI, VS Code, and Claude Code (reported).

CLAUDE.md is Claude Code's own instruction file. It can live at three levels: ~/.claude/CLAUDE.md for personal preferences across projects, the project root for team rules checked into git, and subfolders for module-specific rules. Running /init generates a starter file from the codebase.

You do not need both. Claude Code reads AGENTS.md in place of a CLAUDE.md, so a team that uses several agents can keep one AGENTS.md as the source of truth. Use CLAUDE.md when the rules are specific to Claude Code, such as which skills or subagents to prefer.

A good instruction file is short and concrete:

# Build and test
- Install: npm ci
- Test one file: npm test -- [path]
- Always run the linter before committing

# Conventions
- TypeScript strict mode; no `any`
- New API routes go in src/routes with a matching test

# Never
- Edit files in /generated
- Commit .env files or credentials

For each line, ask whether removing it would cause the agent to make a mistake. If not, delete it. Long instruction files dilute the rules that matter, and anything that only applies to one kind of task belongs in a skill instead.

Installing and sharing skills safely​

Community directories such as skills.sh let you install a published skill with one command (npx skills add owner/repo) and publish your own from a Git repository. Treat an installed skill like any other code you run. Read the SKILL.md and any scripts before installing, prefer skills from sources you can identify, and watch for instructions that tell the agent to fetch remote content, send data elsewhere, or ignore your other rules. A skill's text becomes instructions to your agent, which makes a malicious skill a direct path for prompt injection, the attack where untrusted text steers an agent. Agent Safety and Guardrails covers the broader pattern.

Key takeaways​

  • Instruction files hold the house rules and load every session; skills hold job-specific know-how and load on demand.
  • A skill is a folder with a SKILL.md; only name and description are required, and the description decides when it loads.
  • Agent Skills is an open standard with broad cross-vendor support, so a well-written skill is portable.
  • Keep one AGENTS.md as the cross-agent source of truth; Claude Code reads it in place of CLAUDE.md.
  • Read every third-party skill before installing it; its text becomes your agent's instructions.

From the author​

Not every skill is a prompt. Shutter, built by the author of this site, is a Claude Code plugin whose four skills operate a real browser and ffmpeg to produce screenshots, GIFs, and showcase videos. It is a useful reference for how a skill with real tooling is packaged.

Next steps​