Create Your Own Skills

Skills are the easiest way to customise and extend native Agent behaviour. It just takes a folder, a markdown file, a description, and your Agent knows how it should do something it could not reliably do before. The barrier is low enough that most teams we work with now have a .claude/skills or .agents/skills directory growing faster than anyone is reading. It's not unusual to quickly accumulate over 100 skills.

That growth is the problem. The value of a skill is not in having it on disk. It is in the skill being scoped tightly to how you actually work, audited for what it tells the Agent to do, and used often enough to be worth maintaining. A hoarded skill may unlock something that gets you started, but unless you are customising it to your particular use case, it will always be someone else's idea of how to accomplish a task. Now this might be fine for general work, but increasingly businesses are looking to customise.agents to fit in with their specific working style or sector. The other concerning problem is that skills are a threat vector straight into your computer. There are many, many poisoned skills on the web and having 100 skills that you don't use very often is a very direct threat to the security of your computer.

This piece is for the practitioner who has been collecting skills, starring repositories, and installing plugins, but has not yet sat down to decide which ones are truly useful in their workflows. We will cover what a skill actually is, how.agents decide to use one, where the real risks sit, and how to move from a hoard of snippets from the web to a useful working set.

What a skill actually is

A skill is a folder containing a SKILL.md file with custom guidance for your Agent. This folder can also contain organised folders of instructions, scripts (note these can be any script that can run on your machine - so you can see the risk here), and resources that give Agents additional capabilities.

The mental model that matters: skills are prompt injection, not code execution. The Agent reads the markdown and follows it. Scripts and assets inside the folder are just things the Agent can choose to run or open, not magic that runs on its own.

There are three layers worth understanding, because they map directly to how the Agent loads context.

The metadata

This file starts with YAML frontmatter that includes required metadata: name and description. A minimal skill looks like this:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for the Agent to follow.

At startup, the Agent only pre-loads the metadata for all installed skills into its system prompt. It gives the Agent enough information to decide whether a skill is relevant, without loading the full content. If the Agent thinks the skill applies to the task, it loads the full SKILL.md. This is more token efficient than MCPs, as all MCPs are loaded into the context window for use by the Agent.

This is the single most important thing to internalise. The description is the trigger. The YAML description in SKILL.md is the primary trigger signal; rely on it to decide applicability. A skill with a vague description will either never fire or fire on the wrong tasks. Both are common, and both look the same from the outside: nothing useful happens.

The core markdown

Below the frontmatter sits the body. This is the procedural knowledge: how the Agent should carry out the task and in what order. Treat the body as you would treat onboarding documentation for a new hire. Be specific: name the files, the commands and the constraints and avoid waffle. The Agent will follow what is written.

Scripts, references, and assets

A skill folder can hold more than the markdown. The conventional layout is scripts/, references/, and assets/. After deciding to use a skill, the Agent opens its SKILL.md. It reads only enough to follow the workflow. If SKILL.md points to extra folders such as references/, the Agent loads only the specific files needed for the request; it doesn't bulk-load everything. If scripts/ exist, it prefers running or patching them instead of retyping large code blocks. If assets/ or templates exist, it reuses them instead of recreating from scratch.

This progressive disclosure is the reason skills scale better than stuffing everything into a system prompt. As skills grow, they may include too much content for a single file or context only relevant in certain situations. In these cases, the skill can include additional files in the directory and reference them from SKILL.md. These are additional levels of detail, which the Agent loads only when needed.

How.agents decide to call a skill

There are two paths into a skill:

1. Explicit Path: The user names the skill. In CLI/IDE, run /skills or type /skill-name to mention a skill. When you invoke a skill by name, you have removed all ambiguity.

2. Implicit Path: The Agent can choose a skill when your task matches the skill description. Because implicit matching depends on description, use concise descriptions with clear scope and boundaries.

There is a hard budget here that is easy to miss. To avoid crowding out the rest of the prompt, Claude and Codex limit the amount of space skills take up. For Codex this is 2%, while Claude Code sets it at 1% of the model's context window. If many skills are installed, both shorten skill descriptions first. For large skill sets they may omit some skills from the initial list and show a warning.

The risks of a hoard

Three risks compound as the skills folder grows.

1. Context Dilution: Every skill description sits in the system prompt at the start of a session. A hundred mediocre descriptions push the Agent toward worse matching and leave less room for the work itself.

2. Behavioural Drift: Skills from different authors encode different assumptions about how to write code, what counts as "done", and what to do when something fails. When two skills overlap, the Agent picks one based on description matching, not on which one fits your codebase. The result is inconsistent behaviour that is hard to diagnose because nothing is obviously broken.

3. Security: A skill is an instruction file that runs inside your environment with whatever permissions your Agent has. Skills run in a code execution environment where the Agent can access the filesystem, run bash commands, and execute code. A malicious or careless skill can tell your Agent to exfiltrate credentials, modify CI configuration, add a dependency you would not have approved, or quietly disable a test. The Agent will follow the instructions because that is what the skill is for. Installing a skill from a third party without reading it is closer to running an unaudited shell script than to installing a library, because there is no review process and no signature check. For us this is the biggest issue with a skills hoard - it is unlikely that most collectors would have read everything within a skill thoroughly.

The case for fewer, customised skills

The teams who get the most out of skills are not the ones with the largest libraries. They are the ones who have identified the three or four tasks they repeat most often and have written or rewritten skills to match exactly how they want those tasks done.

This matches the way the Codex team frames it. Keep each skill scoped to one job. Start with 2 to 3 concrete use cases, define clear inputs and outputs, and write the description so it says what the skill does and when to use it.

It also matches the broader argument from Anthropic about why skills exist in the first place. Instead of building new.agents for every use case, companies should rely on a single general Agent powered by a library of skills. Skills are organised collections of files that package composable procedural knowledge for.agents (which will be unique for every business).

The real value add is the procedural knowledge being yours. A generic "write a PR description" skill from a public marketplace will produce generic PR descriptions. A skill that names your repository conventions, your reviewer expectations, your ticket format, and the three things your team always forgets to check will produce PR descriptions that pass review.

This is also where sector context matters. A skill for handling customer workflow in a business context looks very different from the same skill in a side project.

A working pattern

A practical way to convert a hoard into a working set:

Start by listing the tasks you actually ask an Agent to do more than once a week. Five to ten is typical. For each, check whether you have a skill that covers it. If you do, open it and read it end to end. If you have not read it, you do not own it.

For the skills that survive that pass, rewrite the description first. Front-load the trigger words. Be explicit about when the skill should not run. A description like "Use when generating database migrations for our Postgres schema. Do not use for ad-hoc SQL queries or schema inspection." will fire far more reliably than "Helps with database work."

Then rewrite the body to reflect how you work. Replace generic steps with named commands. Replace "run the tests" with the exact test command your repository uses. Replace "follow best practices" with the two or three statements that define what this best practice is. The skills that pay off are the ones that capture the discipline you'd want from any collaborator: break the work down, ship in small pieces, keep track of what you're looking at, and write down why you made the choices you made. The skills make it repeatable in a context where your collaborator has no memory between sessions.

Remove the rest from your skills folder and see if you actually miss any. If you find yourself missing a skill bring it in, but read it and customise as you see fit. A skill you have not read, do not use, and cannot vouch for is a liability that costs you context tokens and exposes you to instructions you have not reviewed.

If you want a sensible default for storage, Codex uses $HOME/.agents/skills for personal skills, and shared team skills can be checked into .agents/skills inside a repository. This is especially helpful for onboarding new teammates. Claude Code uses .claude/skills/ in the project. Either way, treat the shared folder as code: reviewed, versioned, and owned by someone.

The point of skills is not to have the most. It is to have the right ones, customised and written by you and few enough in number that you can keep them honest.