← Blog

Agent Skills: What They Are and How to Install Them

2026-11-09

Agent skills are reusable procedures stored as folders with a SKILL.md file, which an AI agent loads on demand instead of carrying every instruction in its prompt at all times. The format is an open specification at agentskills.io, so a skill written for one agent can be read by another.

This guide explains the format, how an agent finds the right skill, and the two ways to add one. It shows the real commands in POLYROB, an open-source (MIT) self-hosted AI agent. Every POLYROB statement comes from the public repository at release v1.7.8, and the sources are listed at the end. Where POLYROB is limited, the text says so.

What is an agent skill?

A skill is a folder. Inside it sits one required file, SKILL.md, which holds a small block of YAML metadata followed by Markdown instructions. The folder can also hold scripts/, references/ and assets/ directories for supporting material.

The Agent Skills specification (fetched 2026-11-09) sets two required fields. The name must be 1 to 64 characters of lowercase letters, numbers and hyphens, and it must match the folder name. The description must be 1 to 1,024 characters and, in the spec’s words, should describe “both what the skill does and when to use it”.

A minimal skill looks like this:

---
name: pdf-processing
description: Extract text and tables from PDF files. Use when handling PDFs.
---

# PDF processing

Step-by-step instructions the agent follows once this skill is loaded.

That is the whole idea. The SKILL.md file is plain text that a person can read, review and edit. POLYROB reads a skill’s scripts/ files as text and never runs them from the skill loader.

Why use skills instead of one long prompt?

A long system prompt costs attention and tokens on every turn, including turns that never touch the topic. A skill moves a procedure out of the prompt and into a file, and the agent pulls it in only when the task needs it.

POLYROB works this way. In a normal session the agent sees a short index with one line per skill. When a line fits the task, the agent calls its load_skill tool and follows the full instructions. The index line is the skill’s polyrob-when metadata, and it is limited to 60 characters, so the index stays small even with many skills installed.

A skill is also easier to fix than a prompt. You change one file, and only the tasks that load it are affected.

How does the agent pick the right skill?

By reading the index line. There is no keyword matcher in POLYROB: the model reads the one-line descriptions and chooses. That makes the quality of the line matter. “Pulling text or tables out of a PDF” tells the agent when to load the skill. “PDF helper” does not.

For work you want done the same way every time, you can pin skills. A scheduled job or a goal can name skills by id. A pinned skill loads in full when the run starts, as long as the pinned bodies fit a 20,000-character budget, and its prerequisites load first. A pin that does not fit is marked LOAD FIRST in the index. The write is refused if the id names no skill, so a typing error shows up when you set the pin rather than at run time.

Where do skills come from?

POLYROB resolves skills from several places, in this order: built-in, user, pack, project, then external folders. Built-in and pack names are protected, so a skill you install cannot take the name of a built-in one.

Run polyrob skills list to see every skill the agent can load. User and installed skills live in your data home, not in the program folder, so they survive polyrob update.

How do you add a skill to your agent?

There are two paths, and the right one depends on where the skill comes from.

Option 1: Drop a folder in

Put a compliant skill folder in a discovery root, and POLYROB finds it in the next session. No command and no approval step:

mkdir -p ~/.agents/skills/my-skill
# write ~/.agents/skills/my-skill/SKILL.md

Because ~/.claude/skills/ is also scanned, a folder that you already keep there is visible to POLYROB too. Discovered skills load in place and are not threat-scanned, so use this path only for files you wrote or have read. External skills only need a description to load; a non-standard name loads with a warning.

The per-repo roots, ./.agents/skills/ and ./.claude/skills/, are scanned only on a trusted local command line (POLYROB_TRUST_PROJECT_SKILLS, on by default locally). On a server this is forced off, and no environment variable turns it on, because a server’s working directory is the install folder and not your repository.

Option 2: Install it through the scanned pipeline

For a skill from somebody else, use polyrob skills install. It accepts a tap name, a local folder, an owner/repo/subdir GitHub path, a git URL, or a direct HTTPS link to a SKILL.md:

polyrob skills search pdf
polyrob skills install anthropics/skills/pdf
polyrob skills approve pdf

The install clones in a sandbox with git hooks and global config turned off, validates the file, and threat-scans SKILL.md and every text resource. A scan hit refuses the install, and there is no --force. A clean skill goes to a quarantine folder and does nothing until you read it and run polyrob skills approve. Each approval writes a row to an install audit.

Two taps are built in: theselfruleorg/polyrob-skills, marked official, and anthropics/skills, marked trusted. A clean skill installed by name from one of those two goes live without the approve step. A community tap, a git spec or a URL always waits in quarantine. Add your own tap with polyrob skills tap add owner/repo.

Every skill command lives under polyrob skills. The old polyrob skill still works, but the help no longer lists it.

polyrob skills update fetches each installed skill again and prints the old and new content hash and each file that changed, so you see a change before it goes live.

Can the agent write its own skills?

Yes, and this is off on a fresh install. SKILLS_WRITABLE is on by default only when you run locally and have switched autonomy on with polyrob autonomy on.

Since v1.7.7, a skill that your own agent, a scheduled job or the background reviewer writes is live at once, and the earlier text is kept for a rollback. The old SKILLS_WRITABLE_REQUIRE_REVIEW setting is gone. A skill written from a chat that holds someone else’s message, or from a group, stays a draft until you decide. polyrob owner pending lists what waits for you.

Every change is logged with who made it, the hash before and after, and an archive of the earlier body, so skill_manage rollback can restore a previous version. An edit or delete needs the hash of the version the agent read, so a stale edit is refused instead of overwriting a newer one. A rollback of an active skill by the agent waits for your decision.

How do you write a good skill?

1. Write the description as a trigger. Say what the skill does and when to load it. For POLYROB, add a polyrob-when line of 60 characters or fewer under metadata.
2. Keep one procedure per skill. A skill for “incident response” is useful. A skill for “everything about servers” is a second prompt.
3. Name the order of steps and the stop conditions. The built-in incident-response skill, for instance, puts impact first and recovery only on an observed signal.
4. Put long reference material in references/. The agent can read those files when it needs them, and the main file stays short. POLYROB injects a skill body of up to about 20,000 characters before it warns.
5. Validate it. Run polyrob skills validate to check the strict authoring rules before you rely on the skill.

POLYROB only allows the standard top-level fields (name, description, license, compatibility, metadata, allowed-tools), and its own settings go under metadata as polyrob-* keys. That keeps your skill portable to other agents that read the same format.

How does POLYROB treat a skill you did not write?

A skill is instructions that an agent will follow, so treat a third-party skill as untrusted input. POLYROB’s pipeline is built around that: a scan before staging, quarantine until you approve, a sandboxed clone that rejects symlinks and path traversal, HTTPS-only URL installs, and scripts that are read as data and never executed by the skill loader. On a multi-tenant server, skills install and skills approve are owner and command-line only, and there is no REST endpoint for them.

The limits matter too. The scanner returns only “clean” or “hit” today. It cannot judge whether a clean skill gives good advice, so reading the quarantined files is still your job. Discovered skills in the drop-in folders skip the scan entirely.

Where is POLYROB weaker?

The skill system is one part of a young project with a small community. Skill discovery has no aggregator marketplace: there are two built-in taps and the ones you add, and nothing else. A skill from another agent’s ecosystem may assume tools or paths that POLYROB does not have, so test it on a small task before you pin it to a goal. The allowed-tools field is advisory in POLYROB: the agent sees a line naming the declared tools, but no other tool is removed from the session.

FAQ

What is the difference between an agent skill and a tool?

A tool is something the agent can do, such as fetch a web page or run a shell command. A skill is a written procedure that tells the agent how to approach a kind of task, often using several tools. Loading a skill adds instructions, not new abilities.

What is a SKILL.md file?

It is the one required file in a skill folder: YAML metadata with a name and a description, then Markdown instructions. The format is defined by the Agent Skills specification at agentskills.io.

Do agent skills work across different agents?

The file format is shared, so a spec-valid skill can be read by any agent that implements it. What the skill asks the agent to do still depends on the tools that agent has. POLYROB reads skills from ~/.agents/skills/ and ~/.claude/skills/ for this reason.

Do I need a skill for every task?

No. Write one for a procedure you repeat or a mistake you keep correcting. For a one-off request, say what you want in the chat.

Can I stop the agent from writing skills?

Yes. The agent can write skills only when SKILLS_WRITABLE is on, which needs autonomy switched on locally by default. When it is on, the agent’s own skills go live at once, and you can undo any of them with a rollback.

Try it on your own machine

Install POLYROB, run the preflight, and list what the agent can already load:

curl -fsSL https://polyrob.dev/install.sh | bash
polyrob doctor
polyrob skills list

Install POLYROB, see the skills page for the overview, and read the open-source AI agent checklist and the self-hosting guide for the wider setup.

Last updated 2026-11-12: the install commands now sit under polyrob skills, and skills your own agent writes go live at once with a rollback.

Sources

Fetched from the public repository at release v1.7.8 (2026-11-12), https://github.com/theselfruleorg/polyrob/blob/v1.7.8/:

• docs/guide/[email protected] (scopes, precedence, discovery, install, taps, trust, update, pinned skills, history and rollback, safety model, polyrob skills command group, SKILLS_WRITABLE)
• core/skills/[email protected] (allowed fields, 60-character polyrob-when, 20,000-character inject size)
• core/skills/[email protected] (external roots .agents/skills and .claude/skills)
• cli/commands/[email protected] (default taps and trust tiers)
• tools/controller/[email protected] (the load_skill tool)
• cli/commands/[email protected] (list, validate, export)
• docs/[email protected] (SKILLS_WRITABLE, POLYROB_TRUST_PROJECT_SKILLS)
• [email protected] (1.7.7: polyrob skills holds the install commands; SKILLS_WRITABLE_REQUIRE_REVIEW removed)
• data/prompts/skills/[email protected] (built-in skill used as an example)

External: Agent Skills specification, fetched 2026-11-09 (field names and limits).

POLYROB is an open-source AI agent you run and own. Install it or read the docs.