--- title: "One Skill Folder That Works in Every Coding Agent" author: "Harry" published: 2026-10-31T04:48:58.271Z updated: 2026-10-31T05:07:49.185Z category: "Building with AI" tags: ["agent-skills"] canonical: "https://fxblog.dev/posts/agent-skills-one-folder-every-agent" --- # One Skill Folder That Works in Every Coding Agent ## Key takeaways - A skill is a folder with a SKILL.md; the open Agent Skills format lets the same folder work in every major coding agent. - One installer writes .claude/skills, .agents/skills and an AGENTS.md pointer, so no agent needs its own copy. - Descriptions stay under 200 characters because every installed description sits in the context on every request. - validate.py fails a skill in CI for a long description, a SKILL.md over 500 lines, shouting, one agent's tool names or fewer than 3 evals. - Skills ship their own checks: check\_email.py exits 1 on a draft that says "hope this email finds you". > **TL;DR** Keep a copy of each skill per coding agent and the copies drift; write a skill with no check and nobody knows it is broken until an agent misuses it. agent-skills keeps each skill as one folder in the open Agent Skills format, installs it where Claude Code, Codex, Copilot, Cursor and Gemini CLI look, and fails it in CI when it breaks a rule. Its skills ship checks that can fail. > > **Do this:** run `npx skills add https://gitlab.com/agentic-fx/agent-skills` in a project, then ask your agent for an email and watch it run the check. [Part 3](03-meeting-capture.md) ended on a question: can the habits that kept these tools honest, like a check that can fail, reach every coding agent your team uses? This part answers with one folder. Claude Code looks for skills in `.claude/skills`. Codex and Gemini CLI look in `.agents/skills`. Keep a copy in each and you edit two files for every fix. In agent-skills a skill is one folder, written once, and the installer puts it where each agent looks. 1. I Built a Lottery App That Refuses to Predict the Jackpot 2. A Spider Crawls Over My Screen and Remembers What It Read 3. An AI Meeting Assistant That Never Hears the Audio 4. **One Skill Folder That Works in Every Coding Agent** (you are here) 5. An LLM Proxy That Retries a 429 Before Your Client Sees It ## One folder, every agent's path A skill is a folder with a `SKILL.md`. The agent reads its short description on every request, loads the body when a task matches, and opens references and scripts only when a step needs them. The agents disagree only on where to look, so the repo's installer, `scripts/install.py`, writes every place: | Agent | Reads skills from | | --------------------------- | ----------------------------------------- | | Claude Code | `.claude/skills/` | | GitHub Copilot | `.claude/skills/` or `.agents/skills/` | | Codex, Gemini CLI, Windsurf | `.agents/skills/` | | Cursor | `.agents/skills/` (and `.claude/skills/`) | | Anything else | a pointer block in `AGENTS.md` | ![The installer writing skills to .claude/skills and .agents/skills and a marked pointer block to AGENTS.md](https://fxblog.dev/media/01a19049-f6f0-779a-a008-1d1099d1eee0/1600) _Your own AGENTS.md content is kept_ Seven skills are on main today, from drafting emails to diagnosing bugs. ## The honesty line: a check that can fail `docs/authoring.md` marks the rules a script enforces, and a merge request that breaks one fails CI. Among them: 1. **A description of 200 characters at most.** Every installed description sits in the context on every request. The spec allows 1,024, but overflow is dropped silently. 2. **`SKILL.md` under 500 lines.** The rest moves into `references/`. 3. **No shouting.** `MUST`, `NEVER` and `CRITICAL` in capitals make models over-apply a rule. 4. **No tool names that only one agent has.** 5. **At least three evals per skill**, in the format of Anthropic's skill-creator. And one rule for the skill itself: it ends with a check the agent runs, never "review your work". ![validate.py checking every skill and the unit tests running OK](https://fxblog.dev/media/01a19049-fc6d-76ce-9bad-bec4e9408a24/1600) _The same two commands run in CI_ ## The email skill fails its own draft `doc-drafting-emails` ships `check_email.py`. It fails a draft for stock filler, a subject too long for a phone, a body over the word limit for its type, or a placeholder nobody listed to fill in. The agent runs it before handing the draft over: ```text ERROR filler phrase: "hope this email finds you" ``` It exits 1. The skill tells the agent to fix every issue it prints and run it again. ![check_email.py failing a draft on the filler phrase "hope this email finds you", then passing once the phrase is removed](https://fxblog.dev/media/01a1904a-008e-7277-9dfc-104b840558af/1600) _Fail first, then pass_ > **Note** > > Skills here never depend on subagents, because not every agent has them. A step that wants a fresh reviewer says: use a subagent if you can, otherwise follow the checklist yourself. ## Try it In your project, with Node installed: ```sh npx skills add https://gitlab.com/agentic-fx/agent-skills ``` It finds all seven skills and writes them to `.agents/skills`, linked into `.claude/skills` for Claude Code. Then ask your agent to draft an email asking your manager to approve a training course, and watch it run the check before it hands the draft over. > **Tip** > > Want the `AGENTS.md` pointer for other agents, or one skill only? Clone the repo to `~/agent-skills` and run its own installer from your project (Python 3.9 or later, no packages): `python ~/agent-skills/scripts/install.py`. `--only ` installs one skill and what it needs, `--global` installs for every project, and `--dry-run` shows what it would write. Every tool in this series was written by a coding agent, and a Claude Code session can stop mid-task on `429 rate_limit_error`. Part 5, **An LLM Proxy That Retries a 429 Before Your Client Sees It**, asks what a local proxy can honestly do about a rate limit, and what it can't. ## Read this with your AI ```text Read the post "One Skill Folder That Works in Every Coding Agent". 1. Explain why skill descriptions are capped at 200 characters. 2. Check the skills I use (pasted below) against the five rules in the post. ``` > **Success** > > You can write one skill that every agent reads, and give it a check that fails. Next: **An LLM Proxy That Retries a 429 Before Your Client Sees It**. ## FAQ ### Which agents can use these skills? Claude Code reads .claude/skills; Codex, Gemini CLI, Cursor and Windsurf read .agents/skills; Copilot reads either; anything else follows the AGENTS.md pointer. The installer writes all three by default. ### Why are skill descriptions limited to 200 characters? The description is the only part an agent sees before deciding to load a skill, and every installed description is in the context on every request. Long ones cost tokens and can be dropped silently.