Agent skills for development teams: turning team knowledge into AI skills

Right now, skills are the cheapest way for a team to get an AI agent working with its own knowledge instead of the average knowledge of the internet. Not because they are sophisticated technology, because they are not, but because they force you to write down what the team knows in a format the agent only reads when it needs it.

That is the thesis of this series. Everything else is nuance: when a skill adds something and when it is documentation in disguise, how to structure it so it triggers when it should, how to test it, what risks come with installing other people’s skills, and what changes when the knowledge you package belongs to a whole company.

What a skill is, and why it no longer belongs to a single tool

A skill is a folder with a SKILL.md file. That file has a header with a name and a description, and a Markdown body with instructions. Optionally, the folder includes reference files, scripts and other resources.

What sets it apart from a long prompt is how it gets loaded. At first, the agent only sees the name and description of each available skill. When a request matches a description, it reads the SKILL.md; and only if the task requires it does it open the references that file points to. You can have dozens of skills installed without filling the context, because most of their content is never read in any given conversation.

Anthropic published the format as an open standard at agentskills.io at the end of 2025, and since then tools from other vendors have adopted it: OpenAI’s Codex, GitHub Copilot, Gemini CLI, Cursor and VS Code, among others. For a team, that changes the calculation. Writing a skill is no longer a bet on one provider; you are writing a Markdown file that several agents know how to read.

I have checked this with a case of my own. The Illuminate skill we have built at eLearning Media, which helps generate and validate SQL for Blackboard Data, is packaged as a Codex plugin. The SKILL.md is the same one Claude Code would read; the only tool-specific part is the packaging around it. There is no install link yet because ChatGPT does not accept new skills; when it does, or when the skill is in a public repository, the details will be on Consultas SQL para Blackboard (in Spanish).

If you are coming from MCP, the difference is covered in MCP vs Skills. In one sentence: MCP gives the agent tools to act on systems, and a skill gives it judgment about how to do a job.

When a skill is worth it

Not all knowledge deserves a skill. If the model already handles a generic task well, like summarizing a document or writing an ordinary unit test, a skill explaining it only adds more text to read.

A skill pays off when it contains something the model cannot guess. With the Illuminate skill this is obvious: the Blackboard Data schema is not in the training data at the level of detail needed, and an unaided model invents tables and columns with complete confidence. The skill brings the schema, the index of valid fields, the candidate relationships between tables and an explicit rule not to invent anything that is not there. Its value lies in fencing off the terrain; the model already knows how to write SQL.

The same happens in a development team with internal conventions, in-house libraries, deployment procedures or the way a project is structured. That knowledge exists, it is usually scattered between people’s heads and documents nobody reads, and no model ships with it. I already wrote about that use in skills as a team’s living documentation, focused on what to put in a skill and what to leave out.

The opposite mistake exists too, and we have made it quite a few times: creating skills for company processes that actually needed to be defined or automated. A skill on top of a confusing process does not clarify it, and a skill for a fixed sequence does with an agent what a script would do better. How to tell the three cases apart is in when not to create a skill.

How to build a skill that works

Writing the SKILL.md takes ten minutes. Getting the agent to use it when it should, and not when it shouldn’t, takes a lot longer.

The first problem is activation, and it depends almost entirely on the description. A vague description means the skill never triggers or triggers where it has no business. The second is structure: a skill that puts everything in one file forces the agent to read hundreds of lines for any question. The pattern that works best for us is a short SKILL.md that acts as a router and tells the agent which reference to open for each need. All of this, with the Illuminate skill as an example that evolves version by version, is in how to create a skill that works.

Before writing, you have to decide where the content comes from. Few skills are written from scratch; almost all of them distill something that already exists: a Custom GPT, a CLAUDE.md, a vendor’s documentation, the know-how of someone who has been running a process for years. The Illuminate skill was born from a Custom GPT, and one of its files still says so. That distillation process, and what gets lost along the way, is in how to distill a team’s knowledge into skills.

From standalone skills to a team plugin

When a team goes from one skill to several, the question of how to distribute and maintain them comes up. In my team we use an internal Claude Code plugin with skills and commands, distributed through a department marketplace. I cannot publish its contents, but I can explain how the work is split between the pieces a plugin can have.

Skills provide judgment and the agent decides when to use them. Commands chain steps in a fixed order when a person invokes them. Hooks always run, without the agent deciding: if a rule cannot be skipped, such as running the linter after editing a file, it should not depend on the agent remembering. That separation, with examples, is in skills, commands and hooks in a team plugin.

Testing a skill

A skill without tests is an assumption about how the model will behave. There are two things to check: whether it triggers on the requests it is meant for and not on the others, and whether the result with the skill is better than without it.

The second check is the one usually missing. A check that passes the same with and without the skill proves nothing, and a skill whose output does not beat the baseline is dead weight, however well written. How to design those evals, which tools exist and what to do when the model changes is in how to test a skill.

What comes along when you install someone else’s skill

A skill is text the agent obeys, and sometimes it comes with scripts. Installing one from a marketplace without reading it amounts to running a stranger’s instructions with your session’s permissions. The analyses published this year on skills from public registries find security problems in a significant share of them, and injection hidden in reference files is the most common pattern.

What to review, how an injection hides and why reviewing does not replace limiting permissions is in third-party skill security. The underlying problem is the same as with MCP, which I covered in MCP in a company: the problem is permissions.

Beyond code: processes and the company

Skills started as a developer thing, but the pattern works for any procedural knowledge. Two articles in the series step outside the editor.

The first applies skills and commands to a classic problem: modernizing a legacy application. Asking an agent to rewrite an old system produces code that compiles and drops business rules along the way. Our method reverses the order: first the system is documented and someone on the team validates that documentation, and only then is the new version written. It is in modernizing legacy code with AI.

The second is broader: what it means to digitalize a company with AI when adoption data in Spain says very different things depending on who is asking, and where I would start. At work we use n8n less and less, because with AI a script takes minutes and, once dockerized, it deploys like any other service. To me, that change in cost matters more than any autonomous agent. It is in digitalizing a company with AI.

Where to start

If your team has no skills at all, I would not start with a plugin or a marketplace. I would start with a single skill about the knowledge you explain by hand most often: the internal library everyone misuses, the deployment procedure only two people know, or the data schema the model keeps inventing tables for. With a well-written description, a router if the content calls for one, and three or four evals to know whether it adds anything.

If that first skill works, the rest of the series helps you scale. If it doesn’t, the problem is most likely in the description or in the fact that the model could already do the task without help, and both show up in the evals before they show up in production.