Verify agent skills before you install them

Know what a skill does before you trust it.

Paste a public GitHub skill URL. See where it drifts from its plan and what it could reach if it runs — free, in your browser, nothing executed.

Public repo · nothing is executed · install the CLI

Try one:

Security

Constrain what a skill can reach.

Doctor tells you whether an agent will follow a skill. skillspec boundary tells you what a skill can reach if it does — the network hosts, file paths, binaries, and credentials it touches — ranked by risk, then compiles a least-privilege policy you can enforce, without changing the skill and without executing anything in it.

It is a standalone tool: no skill.spec.yml, no adoption of the rest of SkillSpec, and it works on a local folder or a public git URL on any host.

  1. Map a collection to see its shape — skills, resources, orphan files where a payload can hide, and how skills cross-reference.
  2. Assess ranks what each skill can reach by severity (critical / high / medium / low), scope-aware: a skill confined to its own directory is low risk; reaching outside it — a home or absolute path, the network, another skill's files — is what earns review. Documentation examples are qualified, not counted as live effects.
  3. Gate the install: skillspec pull assesses a skill or plugin before it lands on disk and installs it only on approval — across harnesses.
  4. Constrain: compile a deny-by-default policy, and optionally enforce reviewed policies against installed skills through a managed pre-tool hook.

Static analysis: nothing in the package is executed. SkillSpec does not enforce the boundary; a harness, hook, or network policy does. See the boundary guide. 

$ skillspec boundary assess https://github.com/owner/skills

Risk across 18 skills — 1 critical · 0 high · 2 medium · 11 low · 4 clean
2 skill(s) reach beyond their own directory — review before installing
├── CRITICAL  plugins/pack/skills/main
│   ├── [CRITICAL] sends data to the network → exfil.example.net
│   │   └── …/main/report.py#L7
│   └── [HIGH] reads credentials → ~/.aws/credentials
│       └── …/main/report.py#L5
└── MEDIUM  plugins/onboard/skills/setup
    └── [MEDIUM] reads outside its directory → ~/.config/agent

Cleared — no review needed
├── 11 clean · reach nothing outside their own directory
└── 4 low · touch only their own files

Platform shift

Where we are: the boom, and its hidden tax

Skills won. They are now a shared packaging format across major agent surfaces, and the public ecosystem jumped from a small catalog into a real infrastructure layer. The cost is that every new skill also adds routing pressure, context pressure, and trust pressure.

20-day surge 18.5x

Reported growth from 2,179 skills on Jan 16 to 40,285 by early February.

Published skills 40,285

Verified public corpus in the Agent Skills data-driven analysis.

Peak day 8,857

Skills reportedly added on Jan 25 alone at the burst peak.

Name collisions 46%

Listed skills share a name with at least one other skill in the analyzed catalog.

01

The context tax compounds

Every installed skill advertises itself before work starts. At roughly 100 tokens per skill, small libraries feel cheap; large libraries become a standing bill. Codex caps the initial skill list at 2% of context, or 8,000 characters when the window is unknown, then shortens or omits skills. Once selected, the full body is still read; the 40k-skill study reports a median body around 1,414 tokens with a heavy tail.

Failure mode Expensive skills quietly become less discoverable.
02

Discovery is already breaking

In a catalog this large, near-duplicates are normal. About 46% of listed skills share a name with at least one other skill, so the agent is asked to pick the right capability from a pile of similar names and compressed descriptions.

Failure mode Wrong-skill selection becomes routine, not exceptional.
03

The trust gap becomes a security gap

A skill is prose, and prose can be skipped, reframed, or forgotten. Description-only framing selected adversarial variants in 77.6% of paired trials, and context compaction can erase safety rules and push prohibited tool actions from 0% to as high as 59%.

Failure mode The final answer is not proof that the plan was followed.

Sources

  1. Ling, Zhong & Huang, Agent Skills: A Data-Driven Analysis verifies the 40,285-skill corpus; day-by-day growth and peak figures are derived from reported analyses of that dataset.
  2. Microsoft Agent Skills documentation describes the advertise, load, resource, and script stages, including the roughly 100-token advertise tier.
  3. OpenAI Codex Agent Skills documentation describes initial skill-list budgeting, description shortening or omission, and full SKILL.md loading after selection.
  4. Under the Hood of SKILL.md studies semantic supply-chain attacks against skill discovery, selection, and governance.
  5. Governance Decay measures context-compaction failures that erase safety constraints.
  6. Omission Constraints Decay While Commission Constraints Persist analyzes why prohibition-style constraints decay under context pressure.

The real failure

The problem isn't weak skills, it's load-bearing prose.

The most important behavior in a good skill is buried in paragraphs: use this route, never substitute that tool, get approval before the destructive step, prove the test ran.

Drift

The model skips, reorders, or substitutes instructions it reinterprets from scratch.

Waste

The same guidance is reread and repaid on every run, even when only one step matters.

Unprovability

A polished final answer is not evidence that the required path, checks, or tools were used.

You do not fix that by writing better paragraphs. Keep prose for judgment, and move the must-follow parts into a small, checkable contract beside it.

SkillSpec now

SkillSpec: import → execute → align

SkillSpec adds one small file, skill.spec.yml, next to your existing SKILL.md. The skill still works anywhere; the contract just makes the critical parts machine-checkable.

01

Assess

Doctor measures a skill before you trust it: token load, buried instructions, name collisions, missing proof, and public URL risk. It gives you a number, not a vibe.

02

Import

Convert the load-bearing prose once into routes, rules, forbids, deny-by-default tool boundaries, and regression tests that can be reviewed and versioned.

03

Execute

At run time, ask the CLI for the current route, phase, and tool boundary. The manual stays on disk; the agent only holds the slice it needs now.

04

Align

Replay the decision trace and compare the run to the resolved contract. The verdict is honest: aligned, partial, or unproven.

First run explores. Every later run recalls. The trace records which rule caused which route, fingerprinted by the resolved spec and input hash, so drift is visible when the skill changes.

Install next

Make SkillSpec your default skill path.

Install the CLI, open your agent harness, and let SkillSpec guide the first assessment from chat. From there, create, convert, route, and run skills with the same verifier-executor loop you can publish with your project. 

# Terminal: install the CLI.
curl -fsSL https://skillspec.sh/install.sh | sh

# Terminal: see the harness roots SkillSpec can install into.
skillspec install targets

# Terminal, later: install a SkillSpec-backed skill everywhere detected.
# Targets include agents, codex, and claude-local when present.
skillspec install skill ./my-skill --all-detected

# Start your favorite harness: Claude, Codex, or both.
# Ask the agent to assess the skill and explain what it finds.
/skillspec run doctor on ./my-skill

# Convert plain skill prose into a contract. Yes, SkillSpec runs on SkillSpec.
/skillspec import ./my-skill

# Make router mode the default first hop for future skill selection.
/skillspec install router

# Terminal: save a Doctor report when you need an artifact.
# Works with a local SKILL.md, skill folder, GitHub folder, or repo.
# Formats: default text, --markdown, --html, or --json.
skillspec doctor ./my-skill --markdown

What changes

Current skills versus life after SkillSpec.

A

Current skills

A plain skill is useful documentation, but the runtime still depends on model interpretation.

SKILL.md
Instructions When the task mentions deployment, inspect config, credentials, and target.
Required order
  1. Check environment
  2. Run tests
  3. Publish proof
if missing_token: stop_and_explain() deploy --verify
Agent harness chooses how much prose to follow
Intent is not enforcement Steps can be skipped, tools can be improvised, setup can be missed, and proof is easy to lose.
  • Good prose still competes with context pressure.
  • Different harnesses can run the same skill differently.
  • Users must trust that the final answer followed the plan.
B

Life after SkillSpec

The skill ships with a machine-checkable contract and a CLI that guides execution.

SKILL.md
Trampoline Load and follow skill.spec.yml.
skill.spec.yml
  • route
  • phases
  • allowed tools
  • checks
  • proof
The skill becomes executable Routes, phase order, tool boundaries, checks, resume behavior, and final proof are explicit.
  • routes
  • phases
  • tool limits
  • checks
  • proof

Who it is for

For product teams, skill operators, and engineers making agents reliable.

Product teams shipping skills

Ship a product with a skill agents can use correctly: declared routes, allowed tools, required checks, and proof that the workflow completed instead of drifting onto your product.

Agent operators with many skills

Route to the right product skill without loading the whole library. Keep context lean, reduce wrong-skill picks, and get a provable result for each run.

Forward deployment engineers

Baseline drift with Doctor, turn prose into contracts, tune token use, and leave behind durable harness behavior with an audit trail of which rule drove which action.

Adoption path

Try it once. Then make it how you create and use skills.

1

Check the skill you already have

Assess a public URL or a local folder. The report shows where execution can skip, drift, overload context, miss dependencies, or finish without proof. 

# Public GitHub URI
skillspec doctor \
  https://github.com/org/repo/tree/main/skills/example \
  --markdown > .skillspec/reports/skillspec-doctor-baseline.md

# Local folder
skillspec doctor ./skills/example \
  --markdown > .skillspec/reports/skillspec-doctor-baseline.md
2

Install the verifier-executor

Install the CLI so SkillSpec can check private skills, compile contracts, refresh the router, and guide real work from your local checkout. 

curl -fsSL https://skillspec.sh/install.sh | sh
skillspec --help
3

Create or convert the skill

Convert important prose into a contract that names the route, phases, tool boundaries, checks, and completion proof the agent should follow. 

# Existing skill
/skillspec import ./skills/my-skill

# New product skill
Write SKILL.md, then import and prove it.
4

Run through the router by default

Use router mode so skills are selected intentionally, executed through the SkillSpec path, and checked before they become the agent's first answer.

The visible loader stays small while SkillSpec handles routing, phase order, checks, resume, and proof.

5

Ship proof with the skill

Publish the Doctor baseline, generated skill.spec.yml, compiled loader, and alignment report so users can see exactly how the skill is meant to run.

This is the default path for companies shipping agent skills with hardware, software, APIs, or internal operations.