Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.

I think the skills abstraction is great. The principle of progressive disclosure allows us to load only the tokens that are needed. It is the standardized format for AI instructions that I have been looking for. Supporting agent skills is already a baseline expectation of all AI coding tools.

I want to encourage my colleagues to write and maintain skills to accelerate their work. Here I describe how I am doing it.

What exactly are skills?

Skills consist of three elements at minimum:

  • Skill name
  • Skill description
  • Skill content

I will use writing commiting message as an example of a skill.

---
name: write-commit-message
description: Commit message guidelines. Use when writing git commit messages.
---

<skill content>

When the AI coding tool starts a session, it will load the skill name and skill description into the model context.

This is what you see in Claude Code when you run /context.

Skills · /skills

Project
└ write-commit-message: 21 tokens

When the agent needs to write a commit message, it should decide to invoke a skill. When the skill is invoked, the agent will read the skill content. In this case, the skill content contains the information on how to write commit messages.

Why do we need skills?

Skills are needed to instruct the agent on how to do things more accurately and efficiently.

On writing commit messages, the company likely has some standards on how commit message should be written.

For example, the commit message should contain this information:

  • How to write the commit title
  • What to include in the commit description (context, design decisions, test plan)
  • What not to include in the commit description
  • Who the reviewers are
  • What URLs need to be included (for example Slack, Asana)

If agents want to write commit messages accurately without additional instructions, they will need to figure out these requirements by looking at similar commits, or running the unit tests related to the commit message.

However, if you require the agent to learn the commit message pattern on every session by reading many similar commits, this is not efficient. If the agent skips the learning process, the agent is not being accurate. This will still be the case even as models get better, because not every company has the same commit message standards.

Writing commit messages could have been done more accurately and efficiently1. Skill files allow this. When the agent is going to write commit messages, it will “invoke the skill” and read the skill content.

Initially I placed the commit message standards in CLAUDE.md / AGENTS.md. This was a reasonable place to put the instruction because it is globally relevant. I have been advocating for CLAUDE.md to only include globally relevant information. However, this means the commit message instructions are loaded even when the user is not writing a commit message, for example when asking questions about the codebase. There is room for improvement here, regarding efficiency.

Then I moved the commit message standards to the git commit template. Instead of placing the full instructions in CLAUDE.md, I added a pointer to the git commit template. This is what I have been doing before we had skills. This still follows the progressive disclosure principle, because I load the commit message standards only when I write the commit message.

Even though placing the commit message standards in the git commit template fulfills the principle of progressive disclosure, there is still benefit in making write-commit-message a skill. We want to centralize our AI instructions instead of scattering them over the codebase. When we implement telemetry and feedback loops for skills, write-commit-message can also benefit if it is a skill.

When you should write a skill

If you want a process to be done more accurately and efficiently with AI coding tools, you should write a skill. These are some examples where you should think about writing a skill.

You have a resource that you want your agent to access. The resource could be Notion, Slack, Asana, or any internal pages. Instead of playing telephone between the AI coding tool and the resource, you can write a skill that teaches the agent how to read the resource. However, this assumes that your AI coding tool has access to the resources, which you will have to set up first.

You execute repetitive processes that you want automated. For example, every day I am supposed to check the feed statistics for our recommendation system. This involves looking at dashboards. If there are significant movements in the metrics, I need to explain it by looking at commit logs. This should have been a skill.

You want a process to be done more efficiently in the future. One such process is on-call pages. You might already be handling on-call pages with AI coding tools that have access to dashboards and error logs. In the future, you want to handle this more efficiently. You can write a skill that informs the agent of the resources that it should look at and the dead ends that it should be aware of.

There are cases where you should not write a skill.

  • Tasks that the agent could already solve accurately and efficiently. For example, you should not add a skill on how to search the code, because the agent is likely already searching the code in the most efficient manner.2
  • Features that the AI coding tool should already be good at. There should not be a plan-mode or clarify-user-questions skill because AI coding tools should already include this in their system prompt.
  • Workflows that should have been a deterministic script. If I am writing a check-commit-message skill, I should not be asking the agent to run checks that could be unit tests. The agent should not be an expensive linter. If there is still value in writing check-commit-message to check the qualitative aspects of the commit message, the skill should ask the agent to run the relevant unit tests for the deterministic checks.

Skill writing advice

I suggest starting by writing the simplest possible skill that is worth using.

You could look at what you did in the past week and think of:

  • The documents that you need to repeatedly write or review
  • Questions that you need to repeatedly answer
  • Investigations that you need to repeat

Then, think whether any of these processes could be done more accurately and efficiently with AI coding tools.

If so, you have found a good candidate for a skill.

Then write your skill. I suggest starting simple, with only a SKILL.md file.

---
name: <name>
description: <description>
---

<What exactly the skill does>

Example queries
- <example query>

# Workflow

<step by step process>

Checklist
- [ ] Item 1
- [ ] Item 2

# Pitfalls to avoid

<list them>

After writing your skill, you should test it. When you commit your skill, you should include evidence that it is tested. Unlike unit tests, testing a skill is not deterministic, but you should still provide evidence of testing.

These are some ways I think are good evidence of testing:

  • If the skill output is a document, the resulting document could be evidence.
  • If the skill provides instructions on how to read a resource, you could start a new session to see whether the agent could invoke the skill and read the resource without tripping over issues.
  • If the skill helps with an investigation, the investigation thread could be evidence.

Your colleagues will review your skill, just as code is reviewed in the codebase.

Managing skills for the company

As hundreds of colleagues commit skills into the codebase, you will soon have hundreds of skills.

This means that you will have hundreds of skill names, and hundreds of skill descriptions. If each skill is 50 tokens, this will be 5000 tokens. Also depending on the quality of your skill descriptions, the agent might invoke skills unnecessarily, or fail to invoke skills when it is needed.

If you look at the skills, there are skills that are company-wide and there are skills that are team-wide. We should only load company-wide skills into context.

This can be done in Claude Code. For team-wide skills, I can add disable-model-invocation: true to prevent the skill from being loaded in context.

---
name: investigate-speed-feed
description: 
disable-model-invocation: true
---

<skill content>

This will mean that if I go to Claude Code and ask “please investigate feed speed”, the skill will not be invoked. I need to write /investigate-speed-feed. This is fine, because people who need to use the skill should know about the skill.

By separating team-wide skills and company-wide skills, and requiring all team-wide skills to have model invocation disabled, I reduce the risk of the agent not invoking necessary skills or invoking unnecessary skills3.

I organize the team-wide skills and company-wide skills into two folders.

skills/
     ├── company_wide/
     │   └── write-commit-message/
     │       └── SKILL.md
     └── team_wide/
         └── investigate-speed-feed/
             └── SKILL.md

However, the skill standard requires all skills to be at the same level.

So I symlink every skill folder into skills/all.

skills/
     ├── all/
     ├── company_wide/
     └── team_wide/

.claude/skills, .cursor/skills, and .codex/skills are soft symlinks to skills/all.

To enforce that skills follow the intended format, you should write unit tests to test skills.

Currently I have unit tests that check that

  • The skill name is short
  • The skill description follows convention 4
  • Whether the SKILL.md file is under 500 lines
  • Required components in the SKILL.md file (I require example queries to appear as its own section within the first 50 lines.)
  • Whether the symlinks are added correctly

To help your colleagues write skills, you write a skill that helps them write skills.

Initially I used Anthropic’s skill-creator skill to write skills. However I found out there are many unnecessary parts. For example, there is no need for the init_skill.py steps that create all the resource directories. I recommend skills to start simple with just a SKILL.md file.

To help your colleagues improve skills, you again write a skill that helps them improve skills.

There will be a skill-feedback skill where agents can provide feedback on skills. Feedback should be provided when the agent finds an inaccuracy in the skill file, or pitfalls that the skill has not documented. The feedback will be stored in some data lake, which should be queried when we iterate on skills.

I hope this helps you write and improve skills for your company, so that the agents can do things more accurately and efficiently.

Footnotes

  1. If you have not noticed by now, the keywords are accurately and efficiently. ↩

  2. That said, it might still be reasonable to include a skill that helps to search code if the agent could not find the code. You might have some code that is hard to search, for example you might be searching for a string but the actual string is broken into two pieces with each string defined at different places. However, it should not be expected for the agent to trigger this skill for every search, but only when previous search attempts fail. Of course, the better way to solve this is to avoid writing code that requires doing this, or improving your codebase instead. ↩

  3. The field name is disable-model-invocation: true, which unfortunately is a negative. It could have been “invokable skills” or “non-invokable skills”, but it is confusing because users can invoke a skill with the slash command. The more precise term is “model-invokable skills” and “non-model-invokable skills” but that is too long. I am glad that I have arrived at the terms “team-wide skills” and “company-wide skills”. ↩

  4. Anthropic recommends the gerund form. However Anthropic is not really following the conventions they recommend. Currently I only require skill name to be in the format {resource / workflow}-{team name}. This is a problem I should worry when the monorepo actually has a hundred skills. ↩