Sang ThaiAIS
All breakdowns
AISAI coding agents

Agents are just markdown files now

A name, a job, and a short list of tools it's allowed to touch. That's the shape AI coding tools have settled on, and this fall each one added to it. Here's what changed in Claude Code, Codex, Cursor and Antigravity, and the one line that deserves real thought.

Oct 23, 2026 Interactive diagram ↓ Sources ↓ Follow on LinkedIn ↗
The short version
  • More and more agents are defined in short markdown files: a name, a description and the tools they may use.
  • This fall: effort set per subagent call (Claude Code), an /agents view (Codex CLI), a coordinator that doesn't code (Cursor), custom agents shipped in Google plugins (Antigravity).
  • Writing the file got easy. The tools line is the part to think hard about.
Infographic: Agents are just markdown files now. Table of Claude Code (agent files and effort per subagent), Codex (/agents view in the CLI), Cursor (a coordinator that delegates and doesn't code), Antigravity (markdown agents with a plan-only mode, as shown on the image)
The image from the LinkedIn post (tap to open full size)
Fig 1 · How a small agent team runs, and what each tool just changed

01

Your task

Tap any box to see what it does. Pick a tool above to see what its update changed.

What an agent file looks like

Here's the shape, using the fields Claude Code's docs list. This one is my own example, written for this page:

---
name: release-checker
description: Checks a release branch against the checklist. Use before tagging a release.
tools: Read, Grep, Glob
model: sonnet
effort: low
permissionMode: plan
---
You check. You don't change anything.
Report what's missing, with file paths.

Example agent file (Claude Code fields). It lives in .claude/agents/ for one project, or ~/.claude/agents/ for all of them.

  • name and description are required. The description tells the main agent when to hand work to this one.
  • tools is the allowlist. Leave it out and the agent inherits every tool available to subagents.
  • model, effort and permissionMode are optional: which model, how hard it thinks (low to max, depending on the model), and what it may do without asking. plan is one of the modes, but Claude Code ignores a subagent's permissionMode when the main session runs in auto, acceptEdits or bypass mode.

What's new, tool by tool

Claude Code

2.1.292 · Oct 6, 2026Agent files could already set an effort level. Now the Agent tool takes an effort setting per call, so a sub-agent runs at the effort level you ask for. A quick checker doesn't need to think as hard as a planner.

OpenAI Codex

DevDay · Sep 29, 2026The Codex CLI got a new /agents view to delegate work and track multiple tasks at once. The Agents API also added computer use.

Cursor

Projects (beta) · Sep 10, 2026A project's coordinator agent doesn't write code itself. It plans, delegates to agents that implement, and brings the finished work back for you to check.

Google Antigravity

Custom agents in Google plugins · Sep 28, 2026Google teams started packaging custom agents into official plugins. The post's Play example is one you build yourself: a markdown file you save at .agents/agents/play-release-audit.md. It sets permissionMode: plan and tells the agent it works read-only.

The pattern

Small agents with focused jobs, and their powers written down where you can read them. A coordinator that plans but doesn't touch the code. Workers with a short tools list. One place to watch them all.

I use Claude Code and Codex on personal projects, and most of my agents there are markdown files now. Writing them got easy. The line that deserves real thought is the tools list: what each agent is allowed to touch.

Three questions for the tools line

  • Does it need to write anything, or only read? If it only reads, give it read tools only. In Claude Code, a subagent's permissionMode: plan is ignored when your main session runs in auto, acceptEdits or bypass mode, so the tools list is the guard that always holds.
  • Does it need a shell or the network? Those are the tools that turn a mistake into a real-world action.
  • What happens if you leave the list out? In Claude Code, it gets every tool subagents can use. Write the list on purpose.

Tools line left out

name: release-checker
description: Checks a release branch…Inherits every tool available to subagents, shell and connected tools included. One bad instruction and a "checker" can change things.

Tools line written

tools: Read, Grep, GlobCan read and search, nothing else, whatever mode the main session is in. The worst a bad instruction can do is a wrong report.

The file is short. The permissions line is the one that matters. If you've tried more than one of these, which setup fits how you actually work? Tell me on LinkedIn.

Sources and further reading

Each tool's claim comes from its own changelog, docs or announcement. I use Claude Code and Codex; Cursor and Antigravity are described from their changelog and blog.

  1. Claude Code changelog (2.1.292) Anthropic · GitHub · released Oct 6, 2026 (npm) · effort setting on the Agent tool
  2. Subagents Anthropic · Claude Code docs · where agent files live, frontmatter fields, what happens when tools is left out
  3. DevDay 2026 recap OpenAI · Sep 29, 2026 · /agents view in the Codex CLI, computer use in the Agents API
  4. Cursor changelog: Cursor Projects Cursor · Sep 10, 2026 · a coordinator that plans and delegates and doesn't write code
  5. Custom agents in Google plugins Nohe · Google Antigravity blog · Sep 28, 2026 · agents as markdown, permissionMode: plan
AIS

← All breakdowns

Detailed breakdowns of AI and data architecture, diagrams included.

 Next breakdown

You approved the tool. Then the tool changed.

An approval is a moment. A tool is a stream.