AI coding assistants are powerful tools on their own, but out of the box they have no memory of how you prefer to work. Every new conversation starts from zero. You explain your conventions, your preferred tech stack, your project structure, and then you do it again next time. Skills attempt solve this problem by letting you encode reusable expertise that your assistant can draw on automatically.
What Are Skills?
A skill is a markdown file that teaches an AI coding assistant how to perform a specific type of task. The concept is not exclusive to any single tool. Claude Code, OpenAI’s Codex, and Google’s Gemini CLI all support skills, and they all follow the Agent Skills open specification. The idea of encoding reusable instructions for AI assistants is converging across the ecosystem.
Each tool has its own directory convention. Claude Code discovers skills from ~/.claude/skills/, Codex from $~/.agents/skills/, and Gemini CLI from ~/.gemini/skills/. But the core unit is the same everywhere: a SKILL.md file with YAML frontmatter containing a name and description, followed by instructions in markdown. Here is what a simple TDD skill looks like:
---
name: test-driven-development
description: Use when implementing any feature or bugfix,
before writing implementation code.
---
# Test-Driven Development
Write the test first. Watch it fail. Write minimal code
to pass.
No production code without a failing test first.
## The Cycle
1. Write a failing test for the next behavior
2. Run it and confirm it fails
3. Write the minimum code to make it pass
4. Run all tests and confirm they pass
5. Refactor if needed, keeping tests green
...
The description field is what the assistant uses to decide when a skill applies. When you ask it to “implement a new feature,” it matches that against available skill descriptions and loads the relevant one automatically. You do not need to remember which skills exist or explicitly invoke them.
Why Skills Instead of AGENTS.md?
Without skills, you either repeat yourself in every conversation or you rely on AGENTS.md to hold all your preferences in one place. AGENTS.md works fine for project-level context like “use tabs, not spaces” or “this project uses Go modules.” But it breaks down when you need detailed, task-specific guidance.
The TDD skill above is a good example. A thorough version might include rules for test structure, naming conventions, instructions for handling edge cases, and examples of good and bad test patterns. That could easily reach several hundred lines. Putting all of that in an AGENTS.md alongside your project configuration would make it unwieldy and would load that context even when you are doing something entirely unrelated to testing.
Skills provide scoped expertise. They load only when relevant, they can be shared across projects, and they keep your AGENTS.md focused on project-level concerns.
Project-Scoped Skills
Skills do not have to live in your home directory. They can also be placed in a skills directory within a repository, which makes them project-scoped. This is where things get particularly useful. You can commit team-specific skills alongside the code they apply to. A project’s testing conventions, deployment procedures, or code review standards travel with the repository itself, available to anyone who clones it.
All three tools support this. Metadata is loaded at startup, and the full skill content is injected only when activated, so having many skills available does not bloat the context unnecessarily.
Building Effective Skills
The best skills share a few characteristics. They are specific enough to be useful but general enough to apply across situations. They include concrete examples of both good and bad output. And they encode constraints that prevent common mistakes.
A skill for building educational games for my kids, for example, encodes the full development workflow, from project initialization with Vite and React to deployment on my VPS. It captures architectural decisions I made once and do not want to rethink every time, such as using p5.js for rendering and Tailwind for layout. By encoding all of this in the skill, every new project starts from a solid foundation without me having to repeat myself.
The pattern is capturing decisions that were hard to make but should be easy to repeat.
The Current State
Skills across all three tools are still evolving. The mechanism works well for what it does, but there are rough edges. Discovery depends entirely on the description field, which means poorly described skills may not trigger when they should. There is no built-in way to version skills or share them as packages beyond committing them to a repository.
The ecosystem is also young. Most developers using AI coding assistants have not written custom skills, and those who have tend to keep them private. There is no central registry or community repository yet. This means everyone is solving the same problems independently, writing their own variants of common skills for testing, code review, or documentation. The emergence of the Agent Skills specification is a promising step toward standardization, and multiple tools adopting it suggests the pattern has staying power.
Security Concerns
The simplicity of skills is also their biggest security risk. A skill runs with whatever permissions your AI assistant has, which typically includes shell access, file system read/write, and access to environment variables where credentials often live. A large-scale study of over 31,000 skills found that 26.1% contain at least one vulnerability, with data exfiltration and privilege escalation being the most common issues. Snyk’s ToxicSkills research confirmed that malicious skills are already appearing in the wild.
A concrete example: a skill bundling a helper script could quietly read $HOME/.ssh/ or harvest API keys from environment variables, then exfiltrate them to an external server. The user approved the skill once, and from that point on it operates with persistent permissions. There is no code signing, no mandatory security review, and no sandboxing by default. If you install third-party skills, treat them with the same caution you would apply to any other third-party dependency.
Getting Started
If you want to try skills, start small. Pick a task you do repeatedly and notice the instructions you give your assistant each time. Write those instructions as a SKILL.md, test it across a few conversations, and refine based on what works. There is no build step, no compilation, no deployment. You edit a file and the next conversation picks it up.
Once you have a few skills in place, the difference is immediate. Less repeating yourself, more consistent output, and a workflow that improves over time as you refine your instructions.