What are AI agent skills (and how to review one before installing it)

August 10, 202613 minAI, Agents, Skills, Security, Claude Code, Codex, DevOps

Short answer (60 seconds): An AI agent skill is a versioned bundle of instructions (and, optionally, tools and scripts) that an agent loads on demand when the task calls for it. Unlike a prompt (ephemeral text that lives in the chat) or a plugin (code that runs and returns data), a skill is reusable documentation the agent reads when it decides the skill applies. Before installing a third-party skill, review four things: provenance (author and license), permissions (which tools it declares), maintenance (last commit, tests, issues) and attack surface (what it can execute against your filesystem, network and credentials).

If you use Claude Code, Codex CLI, Cursor or any coding assistant with agents that work on your machine, you have seen the concept: there is a .skills/ or .agents/skills/ directory and inside it, Markdown files that teach the agent specific things — how to review your SEO, how to run a migration, how to apply your company's style guide. What almost nobody explains well is what they actually are, how they differ from a prompt or a plugin, and how to audit one before dropping it in your repo. This post is the guide I wish I had the first time I recommended skills to a client.

What a skill is, concretely

A skill is a file (or set of files) that contains:

1. A name and a description that the agent uses to decide whether to load it.
2. Instructions in natural language about when to apply the skill and how to proceed.
3. Optionally, declared tools and scripts with scoped permissions.

The central idea is simple: instead of pasting a long prompt in each conversation, you write a reusable procedure once, version it in your repo, and the agent loads it only when the task matches its description. It is the equivalent of having a procedures manual for your agent.

Minimal anatomy of a skill (typical format, similar to the one used by Claude Code, Codex and others):

my-skill/
└── SKILL.md          # name, description, instructions
    ├── scripts/      # optional: executable code
    └── tools.json    # optional: tool and permission declarations

The SKILL.md file always carries frontmatter with two fields the agent indexes:

---
name: skill-name
description: >-
  A short description the agent uses to decide whether to load it.
  If the task matches this description, the skill is injected into
  context. If not, the agent does not even see it.
---

What comes after the frontmatter is prose instructions. They can be as short as a checklist or as long as a 200-line manual. The agent reads them as additional context when it decides to activate the skill.

What a skill provides (and what it does not)

A skill provides three things, in order of importance:

1. Specialized instructions (the core)

Text that describes a procedure, a convention, or a domain. Typical examples:

• "How to audit the SEO of a page (what to look at, in which order, what to report)"
• "How to write conventional commits in this repo"
• "How to apply the company's design system"
• "How to deploy to production without breaking the pipeline"

This is reusable knowledge that otherwise you would paste in every conversation or re-explain every time you open a new chat.

2. Declared tools (optional)

The skill can declare tools the agent already has available: read a file, run a command, perform a search. What changes with the skill is which tools are exposed and under which conditions. An SEO skill, for example, can declare permission to read public/ and fetch URLs, but not to run system commands.

3. Scripts and utilities (optional)

Some skills include scripts that the agent can invoke. For example, a "regenerate blog images" skill can bring a scripts/regenerate.js that the agent calls when appropriate. These scripts run with the permissions of the user who runs the agent — that is, with access to your filesystem.

What a skill is not:

• It is not a different model from the one you already use.
• It is not a plugin in the classic Chrome/Figma sense (it does not get injected into a UI).
• It is not a parallel agent — it is content the current agent reads.

Skill vs prompt vs plugin: the real difference

This is the most common confusion. The three terms sound similar but do different things.

The clearest way to think about it:

• Prompt = what you say right now.
• Skill = the procedures manual the agent consults.
• Plugin = a tool the agent uses to do something concrete.

Concrete example

Imagine you want your agent to review the SEO of a page before merging a PR.

• Without a skill, with a prompt: you would have to paste the checklist in every chat ("first check the title tag, then the meta description, then the headings…"). It gets lost between sessions.
• With a skill: you write skills/seo-audit/SKILL.md once with the checklist. Every time you ask for an audit, the agent detects the task matches and loads the skill automatically.
• With a plugin: you write a binary like seo-audit-cli that reads the URL and returns a JSON. The agent calls it as a tool.

All three can be combined: the skill tells the agent when and how to audit; the plugin gives the data to do it; the user prompt tells which page to audit.

Who uses skills today (and why it matters)

The pattern went mainstream between 2024 and 2026 with the rise of coding agents. Three concrete references in the ecosystem worth knowing:

• Claude Code (Anthropic): uses .claude/skills/<name>/SKILL.md with name + description frontmatter. Supports tools declared per skill.
• Codex CLI / OpenAI (2026): uses .codex/skills/ with the same pattern, integrating system tools.
• Pi coding agent (the agent reading this file): uses .pi/skills/ and .agents/skills/, also with name + description frontmatter and on-demand loading.
• Cursor, Aider, Continue.dev: each has its own convention, but the pattern is the same — a versioned directory with skills the agent indexes.

Common to all of them: skills are text files in your repo. That has three practical consequences:

1. They are versioned with git. A change in a skill is a reviewable PR, with diff, with code review.
2. They are auditable. Before merging, you look at what the skill does like you look at any code.
3. They are shareable. A central registry (official or community) distributes curated skills. The question is which ones to trust — and that brings us to the checklist.

The security checklist: 4 things you review before installing a skill

A skill is code that runs with your permissions. If you install it without review, you are giving the original author access to your filesystem, your network and potentially your credentials. This is not theoretical — there have already been incidents of malicious skills in public registries in 2025. The minimum checklist before installing any third-party skill:

1. Provenance

• Who wrote it? A known author with track record is different from an anonymous user created yesterday.
• Under which license? MIT/Apache 2 are safe for commercial use. "All rights reserved" or absence of license is a red flag.
• Is it signed or signed by the organization? Some registries publish checksums or signatures. Use them if they exist.
• Does it have history? Look at the git log: if the repo has one initial commit and then two years of silence, distrust it.

2. Permissions

• What tools does it declare? If the skill says "can run system commands" it is different from one that only reads files.
• What operations does it enable? File reads are low risk. Writes to your home, rm -rf, execution of binaries: high risk.
• Does it access the network? Outbound HTTP calls can exfiltrate data. If the skill declares a fetch tool, look at where it calls and with what payload.
• Does it access credentials? If it reads environment variables or files like ~/.aws/credentials, .ssh/, .npmrc, etc., that is a serious red flag.

3. Maintenance

• Does it have recent commits? More than 12 months of inactivity usually means the skill was abandoned — and abandoned means vulnerable to someone taking it over and injecting code.
• Does it have tests? Skills with tests are more trustworthy: it means the author thought about failure cases.
• Are there open issues without a response? A backlog of critical issues without triage is a sign of abandonment.
• Is there a channel for reporting problems? A README with clear instructions on "how to report a vulnerability" is a good sign. The total absence of instructions is a bad sign.

4. Attack surface

• Does the skill run code that touches your filesystem? If yes, which files and with what permissions?
• Does it make network calls? To which hosts? With what data? If you cannot answer, do not install it.
• Does it have external dependencies? A skill that imports a random npm package inherits that package's attack surface (and its transitives').
• Is it obfuscated? Skills with minified code, meaningless variable names or hard-to-follow logic are an immediate red flag. If you cannot read what it does, do not run it.

Summary table

Rule of thumb: if three of the four columns are in "low concern" and the fourth is not concerning, you can install it with monitoring. If two or more are in "high concern", do not install it without an independent audit.

How to create your first skill (5 minutes)

If you want to try the pattern without installing anything third-party, you can create your own skill in your repo. The minimum flow is:

1. Pick a procedure you repeat. Example: "every time I open a PR, I want the agent to review three things before merging".
2. Create a directory .skills/<name>/ (or .agents/skills/<name>/, or whatever your agent uses).
3. Write SKILL.md with name + description frontmatter and the procedure in prose.
4. Version with git and commit. If your agent indexes repo skills, it will appear available without you doing anything else.

A minimal real example, a "PR review" skill:

.agents/skills/pr-review/
└── SKILL.md

---
name: pr-review
description: >-
  Use when the user asks to review a pull request or a diff before
  merging. Covers style guide, tests, basic security and conventional
  commits format.
---

# PR Review

When the user asks to review a PR or a diff:

1. **Style guide** — verify the code follows the repo's style guide
   (`.eslintrc`, `.prettierrc`, `gofmt`, etc.).
2. **Tests** — confirm the change includes tests, or justify why not.
3. **Basic security** — look for hardcoded secrets, calls to endpoints
   without authentication, unvalidated inputs in HTTP handlers.
4. **Conventional commits** — verify the commit message follows the
   `type(scope): description` format.

Report findings in order of severity. Do not approve if security or
tests fail.

That is it. That skill lives in your repo, can be reviewed in a PR, and the agent loads it automatically when you ask for a review. If the style guide changes, you update SKILL.md with a new PR.

When NOT to use skills

You should not use skills when:

• The procedure is one-off. Write it as a prompt in the chat.
• You need complex logic execution. That calls for a plugin/tool, not a skill (skills are text, not application code).
• The team will not maintain the file. An abandoned skill is worse than no skill — because someone may trust it exists and apply it outdated.
• The procedure changes every week. Skills are stable content; if everything changes constantly, maintaining them becomes overhead.

In those cases, a well-written prompt in the team's system prompt or a versioned script is enough.

What is coming next

Three trends you will see in the next 12 months:

1. Signed registries with attestation. Just like npm introduced npm audit and npm signing, skill registries will start requiring signatures and checksums. Trusting a skill will become as routine as trusting a dependency.
2. Skills with permissions declared in the frontmatter. Today the permissions are in the skill's code; by 2027 they will be in YAML, auditable without running anything. It is the equivalent of a package.json with permissions.json.
3. Community curation by domain. Just like GitHub Actions, curated lists by community ("official SEO skills", "official security skills") will emerge that give an implicit layer of trust. Always pick from those lists before the open registry.

Meanwhile, the practical advice is the same: review provenance, permissions, maintenance and surface before installing. If any of the four gives you doubt, do not install it without an audit.

---

Sources and verified data:

• Claude Code skills documentation (Anthropic, 2026) — SKILL.md format, frontmatter and on-demand loading.
• Anthropic Claude Sonnet 5 launch (Jun 30 2026) — pricing reference for cost calculation of skill operations.
• Codex CLI skills reference (OpenAI, 2026) — equivalent pattern in the OpenAI ecosystem.
• Pi coding agent skills format — name + description frontmatter spec.
• OWASP Top 10 for LLM Applications (2025) — framework for evaluating attack surface in agent tooling.
• npm supply chain attack analysis (2025) — precedent on how open registries can compromise a developer environment.

Frequently asked questions

What is an AI agent skill?

A skill is a versioned bundle of instructions and, optionally, tools and scripts that an AI agent loads on demand when the task calls for it. Unlike a prompt (text sent in each conversation) or a plugin (an extension that connects the model to an external system), a skill is reusable content the agent reads only when it decides the skill applies.

How is a skill different from a prompt?

A prompt is text you (or the system) send in each conversation; it lives in the chat. A skill is a versioned Markdown file that describes a procedure or domain, which the agent loads when the task matches its description. Skills are shared, versioned and reviewed like code; prompts are not.

How is a skill different from a plugin or a tool?

A plugin/tool is code that runs and returns data (read a file, call an API). A skill is primarily documentation and instructions: it tells the agent when and how to use the tools it already has. A skill can declare its own tools, but its core is text.

Can skills execute code or connect to the internet?

It depends on the agent. In systems like Claude Code, Codex CLI or similar coding assistants, a skill can include scripts and declare tools with scoped permissions (file reads, command execution, network access). The scope of those permissions is exactly what you need to review before installing one.

What should I review before installing a third-party skill?

Four things: (1) provenance — who wrote it and under which license, (2) permissions — what tools it declares and what operations it enables, (3) maintenance — recent commits, tests and an issues channel, (4) attack surface — whether it runs code that touches your filesystem, network or credentials. If any of the four fails, do not install it without an audit.

Do skills replace system prompts?

No, they complement each other. The system prompt is the agent's "way of being" (tone, global rules, identity). Skills are specific knowledge and procedures loaded on demand. It is the same analogy as an operating system vs applications: the OS gives you the environment, the apps give you capabilities.