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 should I check? | Practical answer |
|---|---|
| Is the package structurally valid? | Check its metadata and directory layout. |
| Which files need review? | Every bundled file, including hidden files and unreferenced helpers. |
| Should I try the skill first? | Keep the initial review static; do not activate the candidate. |
| Does an empty findings list clear installation? | Only within recorded coverage; unresolved files remain unresolved. |
| Where do permissions come from? | The host configuration and authorized task scope. |
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 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.
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.
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 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.
Format and CLI behavior checked on September 14, 2026. Client support and scanner behavior can change; retain the versions used for each review.