Two days of coding, three cleanups. AI agents are very fast at programming — but before you know it, you’ve drowned in chaos. Let’s be honest: nobody can read the walls of text and code that agents produce. If you don’t set up a frame, you will drown in it. If you’re a product manager prototyping new feature, the dev team will be starting from scratch, with a lot of questions. If you’re coding your own app after hours, you won’t know what happened here when you come back to it in a month. That’s why it’s always worth keeping your agents’ context clean, and results and code that are explainable.
Last time we cleaned house on rules (see the earlier article). This time it’s about skills: how to teach your agents reusable workflows, and how to stay in control of what they know and where it comes from. Here’s what a skills audit turned up in my last fast-and-happy-prototyping round:
That audit is where this article’s principle comes from. This works fine for me now, and my main setup is Cursor IDE, an AI agent framework from Google, and Claude Code (as a plugin in Cursor, or in the desktop app).
Every hand-written skill carries a silent maintenance contract: nobody will update it when the framework changes, and it will drift. Both of my failures above are just that contract coming due.
Don’t write skills that already exist. Treat skills like code. A skill is code you own. Before writing code, check whether it’s already open-sourced. Before writing a skill, check whether the vendor already ships it. And once you have it — treat it exactly like code: it lives in the repo, it’s versioned, it’s reviewed, and somebody owns its maintenance. And keep it up to date.
Quick recap from the rules article, because this confusion produces half the bad skills out there:
The litmus test: if it would be a bug for the agent not to know it, it’s a rule. If it’s expertise the agent should pull in on demand, it’s a skill.
The classic smell is a “project rules” skill — one whose description says “ALWAYS read this when working in dir X.” That’s a rule wearing a skill’s costume, and it loads unreliably exactly where reliability is the point. Migrate it to a nested rules file and delete the skill.
Before writing a skill, check first — in this order:
1. The vendor’s official skill suite. Big frameworks increasingly ship one. Vendors like Google and Anthropic publish skills matching their frameworks on their websites or on GitHub — check there first, and always take the official version. If you’re working with Google Cloud and an agent framework, Google’s agents-cli provides a full ADK lifecycle and also publishes a general skills library for cloud. Anthropic ships a range of skills — for document processing, frontend design, and more — in a public GitHub repo.
2. Check community packs. There are a number of sites that offer skills for pretty much any software or topic.
skills.sh is a public registry and "package manager" for agent skills — in practice, the equivalent of npm, except instead of packages it stores SKILL.md files (and their companion scripts/resources) for installing into Claude Code, Cursor, Codex, and so on. It's run by the Vercel Labs team, and the registry is community-driven.
Since it’s an open, community-driven registry (anyone can publish), it’s worth treating installing a skill from there a bit like npm install-ing an unknown package — check the repo and the author before you let their SKILL.md into your agent's context, which has access to your code and your terminal. There are also more "curated" variants of the same idea (e.g. officialskills.sh, which carries skills exclusively from official teams), if you want a narrower, more trusted source than the fully open registry.
Honestly, I haven’t used it much myself, since everything I need I can usually find directly in vendor repos, or — if I need something specific — I have to write it anyway. But if you do pull something in, treat it like any dependency you’d add to your project, and read the source carefully before adopting it. A skill is instructions your agent will follow — an unreviewed community skill is an unreviewed contributor with commit access to your agent’s brain.
3. Write DIY — for the gap the above don’t cover.
This is the right place for your domain knowledge, your expertise, and your specific project workflow.
Sometimes it genuinely is the right call:
Those are my cases, and they’re worth owning. For every new feature, I start with design first — the agent creates a diagram of how it should look, and only after approval does it start implementing.
Even then, one discipline applies: keep DIY skills project-agnostic. The moment a skill says “in this repo, never import X,” it has smuggled in a rule. Move that line to the project’s rules file and keep the skill portable.
Don’t install skills into your local user directory — not if the code they support is shared, or ever will be — this is my mantra.
The reasoning is the same as for any dependency. If a skill shapes how code in a repo gets written, then a teammate cloning that repo without the skill gets a differently-behaving agent than you do. That’s the rules-drift disease from the last, reincarnated. Skills that belong to a project belong in the project: committed, versioned, reviewed and visible in git log.
The one honest exception: you’re solo, vibe-coding apps for your own use in evening, and the “team” is you and your agent. Then user-level skills are fine — they’re personal utilities.
But solo-plus-one-teammate already disqualifies it. The moment you touch shared code (or hand off to another agent), user-level skills become a liability, because tools like Claude Code and Cursor read user-level skills first. Bad things happen in two flavors: either the same skill loads twice (your user copy plus the project copy, drifted apart), or — sneakier — something loads that you forgot you even had in that directory, quietly steering the agent while your teammate’s agent behaves differently on the exact same repo. The same applies if you use different coding agents for the same project — e.g. Cursor and Claude Code, which is my standard set. If you have two skills directories, .cursor and .claude, and they're not consistent, you'll get different behavior from both.
Back to Cursor . Cursor loads skills automatically from these directories:
For compatibility, Cursor also loads skills from the Claude and Codex directories: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/.
What actually happens in practice:
Cursor scans all of these directories (.agents/skills/, .cursor/skills/, .claude/skills/, .codex/skills/, plus their global equivalents under ~/) and **treats every **SKILL.md it finds as a separate entity . If you have adk-google in both .agents/skills/adk-google/ and .cursor/skills/adk-google/, the skill shows up in context twice, as separate entries (name, description, path).
This was confirmed by a bug reported on Cursor’s forum, where a user showed an even more extreme case — the same skill, planning-with-files, loaded from **11 different paths **simultaneously (Codex, Claude Code, nested compatibility directories, and so on). Cursor itself recommends keeping skills in only one directory — for example, ~/.cursor/skills/ (or .cursor/skills/ at the project level).
Consequences:
Cursor **did introduce partial deduplication at some point **— at least for the .claude/skills ↔ .cursor/skills pair, when the paths are correctly recognized.
Tools multiply skill directories — .claude/skills, .cursor/skills, .agents/skills — and without a convention you get N versions drifting apart. Same disease, same cure as with rules: one source of real files, everything else points to it.
Since Cursor reads from .agents (or from .claude, if given), Antigravity reads from .agents, Claude reads from .claude, and .cursor/skills isn't needed, I settled on this setup:
.agents/skills ← the ONLY real files, committed to the repo.claude/skills → ../.agents/skills (symlink)
(Yes — last time I told you not to symlink CLAUDE.md to AGENTS.md. That advice still stands: rule files need different frontmatter per tool, and @-imports solve that cleanly. Skill directories have no per-tool metadata to carry and no import mechanism to lean on, so here the symlink is the right tool. Hopefully, someday, everyone agrees to standardize and just puts everything into .agents/skills.)
A couple of practical notes from setting this up:
This works pretty well for plain skills in .md format. But many vendors now ship a full package: skills and CLI tools (scripts which can be run by agents). Example: Google Agents CLI. This is a bit of an uphill battle, because if you run the default installation, the whole package lands in your local user folder (.gemini and/or .agents). You can live with that and add symlinks in your local project skills (.skills, .claude/skills, etc.), but I will recommend to install and manage everything on the project level.
So don’t run uv tool install google-agents-cli if you only want the project's venv. And note that agents-cli setup still tries a global uv tool install regardless.
My CLI tools live there:
[dependency-groups]skills = [ "google-agents-cli==1.2.1",]
This will install the CLI into your .venv. But then you need to remember to check and adjust the instructions for the agent inside the .md files — because, for example, Google's skills tell the agent to look for the CLI in .local by default, and to install it if it's not found there, e.g.:
Requires: agents-cli (uv tool install google-agents-cli) - install uv first if needed.
This means the agent still tries a global uv tool install regardless,
and the skills will land in your .local again.
You can replace that with:
Requires: agents-cli (always check .venv/bin or ask for installation: uv tool install google-agents-cli) - install uvfirst if needed.
The risk is that after a skill update, this edit disappears and the agent tries to install the CLI globally again. Here the rule comes into play — add an entry to the main AGENTS.md rules file:
After you installed your CLI with:
cd backenduv sync --group skills
add .md files to your project: <project>/.agents/skills:
cd /path/to/your/project# install into the workspace (project).venv/bin/agents-cli setup --workspace --skip-auth
This command automatically finds the agents directory you set up before, e.g. .agents/skills and .claude/skills and put the .md files there.
Because they are instruction files. The same discipline from last time applies, plus a few skill-specific habits:
Two days of vibe-coded output that looks production-ready is exactly the illusory-productivity trap from the top of this article: fast, confident, and not worth trusting until someone has drawn a frame around what the agent is allowed to assume.
Set the skills up once, and the payoff is the same as with rules: adopting a new tool costs a symlink, upgrading a suite is a reviewable diff, and your agent stops confidently teaching you last year’s API.
This is what context engineering actually buys you: simple but rigid frames for the agent. Simple, so they don’t generate overhead for the human. Rigid, so the agent doesn’t drift every time it gets a new task.
And if this saved you from teaching your agent a bug (or from writing a skill it had already shipped) — a few claps 👏 help this reach the next person.
Next up: the SPEC/PRD workflow — how not to drown, and not eat your own tail.
Agent Skills: Vendor First, Commit Always was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.