Agent Skills specification and security review

The Agent Skills specification describes how to package reusable instructions for an agent. Before installation, the practical question is what those instructions and their supporting files would cause your agent to do with its existing access.

This is Beam's explanation of the upstream format and our recommended review workflow. The workflow is additional security guidance, not a certification defined by the specification.

What does the Agent Skills specification require?

A skill needs a directory containing SKILL.md: YAML frontmatter followed by Markdown instructions. Required fields are name and description. The name must match its directory, use lowercase letters, numbers, and hyphens, stay within 64 characters, and avoid leading, trailing, or consecutive hyphens. The description is nonempty and at most 1,024 characters. Optional fields include license, compatibility, metadata, and experimental allowed-tools; metadata values are strings. Supporting directories commonly include scripts, references, and assets. These are format rules and conventions from the upstream Agent Skills specification.

For example, our illustrative review skill could use:

review-release/
  SKILL.md
  references/review-policy.md
  assets/report-template.md

---
name: review-release
description: Review a proposed release checklist and report missing evidence.
metadata:
  author: example-team
  version: "1.0.0"
---

The host may discover metadata before loading the full instructions, then read supporting resources when needed. Installation locations and discovery behavior depend on the client. The Agent Skills client implementation guide explains this loading sequence and recommends trust checks for project skills. Our review recommendation follows from that behavior: quarantine candidates outside directories your agent automatically discovers.

How do agents load a skill, and why does that matter for review?

The specification describes what it calls progressive disclosure. Three tiers load at different times:

1. Metadata. The name and description of every installed skill are loaded at startup, roughly 100 tokens each according to the specification.
2. Instructions. The full SKILL.md body loads when the agent decides the skill is relevant. The specification recommends staying under 5,000 tokens.
3. Resources. Files in scripts/, references/ and assets/ load only when the instructions point to them.

For a reviewer, the consequence is that what the agent reads first is not what the skill can eventually reach. A short, tidy SKILL.md can reference a script, which can reference another file. The client implementation guide recommends keeping references one level deep from SKILL.md, but that is advice to authors, not a rule a package must follow. A reviewer has to follow every reference, not just the ones in the first file.

There is also a discovery question. The same guide says most locally running agents scan at least two scopes: a project directory relative to the working directory, and a user directory relative to the home directory. Within each, many clients look at both their own native path and the cross-client .agents/skills/ convention, and some also look at .claude/skills/. The guide notes that the specification itself does not say where skill directories live. It only defines what goes inside them.

That has a practical effect: a skill dropped into any of those paths may be picked up by more than one client. When you quarantine a candidate, keep it outside every path your agents scan, not just the one you intend to use.

What do the vendors say about trust?

Two statements are worth reading before you decide how much review a skill needs.

The client implementation guide warns about project-level skills: they "come from the repository being worked on, which may be untrusted (e.g., a freshly cloned open-source project)." It suggests gating project skill loading on a trust check, so an untrusted repository cannot "silently inject instructions into the agent's context."

Anthropic's Agent Skills overview is more direct. It says to use skills only from trusted sources, meaning ones you created or obtained from Anthropic, and that a malicious skill can direct Claude "to invoke tools or execute code in ways that don't match the Skill's stated purpose." Its listed concerns line up with the review steps above: audit every bundled file, treat skills that fetch external URLs as particular risk because "even trustworthy Skills can be compromised if their external dependencies change over time," and treat adding a skill like installing software.

Note that Claude Code's own skills documentation says a skill folder can also be loaded as a plugin that bundles agents, hooks and MCP servers, and that in a project's .claude/skills/ this requires accepting the workspace trust dialog first. A skill is therefore not always just text. Check the skill folder for a .claude-plugin/plugin.json or similar files before you treat it as instructions only.

How do you review without activation?

Start with an artifact identity: origin, exact commit or release, retrieval time, and a file manifest with cryptographic digests. Compare the installed bytes with that manifest immediately before installation. A digest identifies content; an independently verified signature or provenance statement can provide additional evidence about origin. SLSA's artifact verification guidance describes checking artifact digests alongside provenance and trusted builder identities.

Inspect an inert copy using trusted local tools. Do not invoke its installer, run bundled tests, import its Python modules, or launch its scripts to discover what they do. Those actions execute candidate code. Preview archives with tooling that rejects path traversal and imposes extraction limits; report an archive as unreviewed if you cannot inspect it safely.

Inventory hidden files, nested resources, symlinks, executable files, configuration, and package manifests. Record symlinks without following targets outside the review boundary. Account for every file as reviewed, excluded with a reason, or unresolved. A binary helper with no reviewed source is a coverage gap even when SKILL.md looks ordinary.

Trace each instruction into the resource it uses. If a helper downloads another script, record the dependency and destination; do not fetch and execute it. An unavailable dependency prevents a complete assessment. The same inventory discipline applies to model loaders and datasets, covered in our AI asset and model security guide.

What does a manifest-first review look like in practice?

The steps below use ordinary tools and make no assumptions about Beam. Work on a copy in a directory your agents do not scan.

1. Record identity. Note the source URL, the exact tag or commit and the date you retrieved it. For a release archive, record the digest published by the author, if any, and compute your own.
2. Build a manifest. List every file, including hidden ones, with its size and a SHA-256 digest. find . -type f -print0 | xargs -0 shasum -a 256 produces one on macOS and Linux. Store the output with your review notes.
3. Flag file types. Separate text files you can read from binaries, archives and anything executable. Mark binaries without reviewable source as unresolved.
4. Check the frontmatter against the rules. Confirm that name matches the directory and the stated limits, and read description as an attacker would: it is loaded for every session, before any activation, so a description can influence the agent's choices without the skill ever running.
5. Follow every reference. For each path, URL or command named in SKILL.md, open the target. List any URL the skill would fetch at runtime as an external dependency you cannot review.
6. Read the scripts without running them. Look for network calls, writes outside the working directory, reads of credential locations, shell invocations built from variables, and anything that edits agent configuration.
7. Write the decision with its coverage. State which files you reviewed, which you skipped and why.

The description point deserves emphasis. The specification says metadata for all skills loads at startup, so that field is the one piece of the skill that is always in the agent's context. A description that claims broad trigger conditions, such as "use for any task", can cause an agent to reach for the skill more often than the author's stated purpose would justify. Treat an overly broad description as a finding to look at, not as a style issue.

Which instructions deserve closer inspection?

Read for behavior: credential access, outbound delivery, destructive writes, persistence, privilege changes, and attempts to alter the review. A package that tells the reviewer to suppress findings is interfering with the evaluation regardless of whether its installation commands appear harmless.

Distinguish quoted attack examples from operational instructions. A security lesson might quote a request to disclose credentials as a negative example; another package might issue the same request as a prerequisite. Record the surrounding context and whether a script or workflow makes it actionable. Labels such as “example” are evidence to examine, not automatic exemptions.

OWASP's prompt injection guidance covers hostile instructions in external content, obfuscation, and separating instructions from data. Apply that separation to the review itself: candidate text is evidence, never authority to change scope, conceal a result, or request more access. Our coding assistant security guide explains the broader agent threat model.

What goes wrong after the review?

A clean review describes one set of bytes at one moment. Three things can change that without you noticing.

• Updates. A skill installed from a repository or registry can change when you pull. Anthropic's overview names this directly for skills that depend on external sources. Treat every update as a new artifact: compare the new manifest with the one you reviewed, and re-review the files whose digests changed.
• Runtime fetches. If a script downloads a file when it runs, the bytes you reviewed are not the bytes that will execute. Record the dependency as unresolved. If you cannot accept that, decline the skill or vendor a pinned copy that you have reviewed.
• Shadowing. The client guide says that when two skills share a name, most implementations let project-level skills override user-level ones, and it recommends logging a warning. A repository you clone could therefore ship a skill with the same name as one you already trust. After cloning an unfamiliar project, check whether its skill directories contain names you already use.

None of these is a flaw in the specification. They follow from the fact that a skill is a portable folder of text and code with no signature or permission model of its own. The specification marks allowed-tools as experimental, so the host, not the package, has to supply the boundary.

Do permission declarations grant access?

Treat every candidate declaration as something to compare against the task. A request for shell access to format a Markdown checklist needs a concrete justification. A compatibility note listing network requirements does not authorize sending repository contents anywhere.

The specification marks allowed-tools as experimental and host support varies. Inspect the host's actual behavior rather than assuming a portable enforcement boundary. Our recommendation is to grant the narrowest permissions the authorized task requires and enforce them outside the skill, through the host or sandbox. Review MCP connections separately using our practical MCP security guide.

Where does Beam scanning fit?

With the standalone Beam CLI already installed from a trusted source, this command scans one file locally:

beam scan /absolute/path/to/quarantine/review-release/SKILL.md

The command prints a JSON report without contacting the collector unless --save is supplied. It does not walk the directory. Use it for individual eligible text files after checking their paths; combine the reports with the manifest and manual review.

The implementation rejects empty text and text exceeding 500,000 JavaScript string code units, with a separate 2,000,000-byte file-read guard. A successful process exit can still include findings. Inspect the report's findings array, and treat read errors or oversized files as incomplete coverage. These details come from the standalone CLI's src/core.ts, src/client.ts, and src/cli.ts, reviewed for this article.

Heuristic scanning can miss novel instructions and flag benign documentation. It does not install, approve, or block the candidate. A report's content hash also does not identify the rest of the package.

What are the common review mistakes?

• Reviewing only SKILL.md. Scripts and references are where behavior usually lives. A reviewer who stops at the instruction file has covered the part that is easiest to read, not the part that does the work.
• Running the skill to see what it does. That is execution, not review, and it uses the access you were trying to protect.
• Reading a zero-findings report as approval. Beam's own documentation says a successful process exit "is not a 'zero findings' exit status" and that scanning gives evidence for a human decision. It also says the scanner does not recursively audit every referenced file or contact servers named in the input.
• Trusting labels. A heading such as "example" or "test" does not make a destructive command inert. Check whether anything can execute it.
• Skipping coverage notes. If you cannot say which files you did not read, you cannot tell later whether a problem was inside your review or outside it.

What should the final report contain?

Keep the decision traceable to evidence. Record artifact identity, reviewed files, excluded files, unavailable dependencies, scanner version and rule configuration, requested permissions, and findings with file locations. Redact secrets from excerpts. Separate severity from confidence: a potential high-impact operation can still need further evidence.

Use explicit outcomes such as “reject,” “changes required,” or “no blocking findings within reviewed scope.” If essential content is unavailable, record “incomplete” instead of approving by omission. Installation should use the reviewed artifact; updates require a new comparison and review.

After installation, runtime visibility answers a different question: what the agent actually did. Continue with our agent monitoring guide and vibe coding security checklist. Visit agentbeam.com for advanced monitoring and control options, including self-hosting guidance when further oversight is needed. A review does not automatically enable monitoring or enforcement. For an example of a powerful skill worth reviewing this way, see Cloudflare's security-audit skill.

Related: vlt 1.5.0 can now link skills shipped in npm dependencies into agent directories, which makes this review step more important.

Related reading: NVIDIA SkillSpector, an open-source scanner for agent skills.

Format and CLI behavior first checked on September 14, 2026; vendor guidance re-read on October 20, 2026. Client support and scanner behavior can change; retain the versions used for each review.