Skills and AGENTS.md Beat Homegrown Specs

You've probably done this: opened a doc to lay down rules for your AI coding agent—your own format, your own filename. RULES.md, GUIDE.txt, or a prompt snippet you've kept for months. Then you switch tools and the rules die: the new assistant doesn't know your filename, so you re-explain everything from scratch.

Here's the thing: the standard for this already exists, and it won. For project instructions it's AGENTS.md; for reusable capability it's Skills. Inventing your own format isn't personality—it's opting out of an ecosystem. But that's only half the story. The standard gives you a shell; what goes inside—the real rules of your project, your own working habits—only you can write. Four things below: why to adopt the standards, when a Skill is worth writing, why your AGENTS.md must be handwritten, and our init Skill.

TL;DR:

• AGENTS.md is read natively by 24 mainstream tools and carried by 60,000+ open-source projects; the Skills spec, open-sourced by Anthropic, is spreading across agent products
• Scale effects, three sources: models already speak the format, community Skills install and run, someone else maintains the spec
• The line for writing a Skill: you've walked the agent through the same multi-step flow three times or more
• AGENTS.md owns the project (it follows the repo); Skills own the process (they follow you)—two layers, no conflict
• Your tool's built-in /init produces a generic repo summary; your init Skill encodes your habits
• Ours runs four idempotent steps: research the project and write AGENTS.md, create a scratch dir, configure .gitignore, finish git safely

Don't roll your own spec: AGENTS.md and Skills already won

First, where the two standards sit today.

AGENTS.md is the README-for-agents: a file at the repo root that tells AI coding assistants what this project is, how to build it, and what not to touch. It's an open standard shaped by OpenAI, Google, Cursor and others, now stewarded by the Agentic AI Foundation under the Linux Foundation; the official site lists 24 tools with native support, from OpenAI Codex and Gemini CLI to Cursor and GitHub Copilot1. Over 60,000 open-source projects on GitHub carry one, and the spec even defines nesting for monorepos: the closest AGENTS.md to the file you're editing wins1.

A Skill is a folder that packages a complete way of doing a job: a SKILL.md stating who I am, when to use me, and the steps—plus optional templates, scripts, and references. The format came from Anthropic, was released as an open standard in late 2025, and any agent product is free to implement it2.

Sure, you could define your own format. But then you face three things alone.

First, the model has to learn your format on the spot. Agents discover and load AGENTS.md automatically at startup; for Skills, they route on the frontmatter description—loading only names and descriptions first, reading the body once triggered, so long tasks don't blow up the context window3. That plumbing is tuned by the vendors. Nobody tuned it for your homemade format: your agent learns it from whatever you paste into the chat, and long documents start losing information.

Second, you forfeit the reuse economy. Nobody invents a private WordPress plugin format—which is why tens of thousands of plugins interoperate: write one, anyone can install it. Skills work the same way: community skills install and run, and what you distill travels across projects and tools. With a homemade format, none of that exists for you.

Third, nobody carries the evolution for you. A foundation stewards the standard; the community argues out upgrades and compatibility. Your private spec has a maintainer roster of exactly one.

In short: what you save by skipping the standard is far less than what you pay for leaving the ecosystem. This isn't taste; it's arithmetic.

When a task deserves to become a Skill

Standards are great, but not everything should be a Skill. The test is one line: if you've walked an agent through the same multi-step flow three times or more, extract it.

The signals are clear: more than one step, stable inputs and outputs, and pitfalls only you know about. The few dozen Skills we run daily—publishing npm packages, generating artwork, initializing projects—are all "same every time, easy to miss every time" work. A lesson like "run npm pack before publishing to inspect what actually ships" is worth saying aloud twice; the third time, it becomes a file.

The flip side: one-off tasks and single-sentence tasks need nothing—just say it. Wrapping them in a Skill adds indirection for no reuse. The essence of a Skill is freezing spoken experience into a reusable file: the description is routing information for the model (when to think of me); the body is the manual for the executor (what to do once invoked). Half of a Skill's quality is whether its description states the trigger and the boundaries clearly.

AGENTS.md owns the project; Skills own the process

The two standards don't compete—they manage different layers:

• Skills follow you: "how is this kind of work done," reused across projects—releasing, imaging, initializing
• AGENTS.md follows the repo: "what is this place and what must never be touched" for one project—stack, verification commands, red lines

Why must the AGENTS.md content be handwritten? Because a tool can survey a repo's surface facts but not your real rules. "Bilingual copy must be updated on both sides," "run this command after editing articles," "does pushing to main trigger a deploy"—these live in the maintainer's head; no generic template generates them. The spec deliberately keeps the barrier on the floor: no required fields, plain Markdown, write as much as you want1—precisely because it's an empty shell, it's yours to fill.

The payoff is immediate. The per-project briefing cost drops to zero—every new session walks in already knowing the rules. And red lines get a backstop: "never push on your own," "don't touch the production server"—once written into AGENTS.md, every session reads them, and you stop policing by hand.

Initializing a project: skip the built-in /init

Which brings us to the most typical scenario: you take over a new directory—how does the agent get up to speed?

Many agent tools ship a /init command: scan the repo, generate an AGENTS.md. It works—but what it produces is a generic repo summary: stack, structure, build commands; every vendor's /init output looks alike. It surveys the repo; it doesn't know you. It doesn't know which fixed sections your AGENTS.md should have, that you want a scratch directory, or what your commit discipline is.

Our answer is an init Skill of our own. The difference isn't the degree of automation—it's whose knowledge gets encoded. The built-in /init encodes "how to summarize a repository"; our init Skill encodes "how I start work": AGENTS.md grown from our template, git finished by our discipline. One sentence at kickoff gets you not just a manual but a workspace laid out the way you actually work.

What our init Skill looks like

Finally, a teardown of the init Skill we maintain.

Three files: a 63-line main file holding only the outer workflow; a ~100-line "AGENTS.md authoring spec" under references/ holding the template and research requirements; and one real-world finished example. The layering is itself a lesson in Skill writing: thin outside, thick inside, load on demand—the same idea as the spec's progressive disclosure.

The frontmatter has just two fields, and the valuable one is the description. Ours lists trigger phrases ("initialize the project," "new project kickoff," "write an AGENTS.md like project X's") and an exclusion clause (if only AGENTS.md is wanted, run step one only). That half is the router written for the model—it deserves constant polishing.

The body is a four-step workflow:

## 1. Generate AGENTS.md
- Read the authoring spec in references/ first, then follow it
- Research project facts: README, package.json, git log, CI config—write only what's verified
- If AGENTS.md exists: skip, never rewrite

## 2. Create the .temp directory
- Home for drafts and experimental scripts; stays out of version control

## 3. Configure .gitignore
- Append at the end only; touch nothing else in the file

## 4. Finish git (three branches)
- No repo → init, then one full initial commit (preview first; ask if secrets show up)
- Existing repo → commit only .gitignore, path-scoped; never sweep in what someone else already staged
- AGENTS.md already tracked → ask first; untouched until confirmed

Three design principles worth copying:

• Idempotency: every step checks before it acts; running twice yields no double effects—an init Skill isn't a one-shot script, it's an on-call process
• Red lines written into the body: "no git add -A in an existing repo" doesn't rest on the model's discretion; it rests on black ink
• Template and workflow separated: template upgrades edit references/, workflow upgrades edit the main file—no coupling

This Skill's default choice is keeping AGENTS.md and the scratch dir local and out of the repo. If your team prefers project rules to travel with the repository, change that clause—it's your template.

The standard is the shell; the habits are the core

To close: adopting Skills and AGENTS.md isn't a taste call. Rolling your own format means maintaining a spec nobody else supports; adopting the standard means taking—for free—24 tools' worth of integration, a community's accumulated skills, and a maintained evolution path. That trade has no suspense.

But what the ecosystem hands you is only the container. What goes in—your understanding of the project, the pitfalls you've hit, the order you work in—the spec can't supply and shouldn't: that's your way of working itself. Seen in two layers, the conclusion is plain: conform on format, individuate on content. The ecosystem makes agents recognize your files; making them recognize your work—only you can write that down.