The anatomy of an agent skill

The package is the unit of review

In the Agent Skills format, a package contains a required SKILL.md file and may include scripts, reference material, assets, and other files. The format describes how a package is organized; safety depends on what that package actually says and does.

Inventory the directory recursively before deciding whether it is trustworthy. A reviewer should be able to explain why every executable resource is included, which document refers to it, and what its intended inputs and outputs are.

Follow the loading path

A skill may be discovered from its metadata before its full instruction body is loaded. Additional material can be consulted later. A complete review therefore follows the path from discovery to activation to supporting resources.

Make a simple file map: entry file, referenced file, code entry point, dependency, destination. Annotate paths that leave the package, including URLs and environment-specific files. This is a review aid, not an assumption that every host loads content in the same way.

Metadata and instructions

Review whether the name and description honestly describe the task. Broad claims such as “required for every task” deserve scrutiny when they are unrelated to the skill’s purpose. In the instruction body, look for hidden prerequisites, changes to expected destinations, and requests to suppress information from the user.

Document the intended behavior positively: the skill reads these inputs, produces this output, and uses these capabilities. That specification makes unrelated behavior easier to detect.

Supporting content and code

References can contain instructions even when named as documentation. Templates can carry hidden content into an output. Scripts can act outside the model’s visible reasoning. Review these surfaces as separate inputs with their own provenance.

For code, record file access, processes launched, dependency resolution, and network behavior. For assets, ask whether content is copied, extracted, executed, or interpreted by another component.

A useful inventory record

• Package identity, source, revision, and review date.
• File list and intended role of each file.
• Code entry points and dependency versions.
• Remote resources and allowed destinations.
• Host assumptions, permissions, and expected outputs.
• Unresolved questions and the conditions for re-review.

A valid format check answers “can the host read this package?” Keep that answer separate from “should this package receive these permissions?”

Worked example: the package listing is not the package

A registry page displays SKILL.md and a small script. The downloaded archive also contains a README, a helper directory, and a configuration template. A review based on the page has a coverage gap before any content has been judged malicious. The relevant artifact is the package that can be loaded, not the most convenient preview of it.

Work through the evidence

Create an inventory from the exact archive or repository revision: relative path, type, size, identity hash, entry-point relationship, and review status. List remote resources separately because they can change without altering the local package. Mark binaries, unsupported formats, large files, symlinks, and failed parsing explicitly. Do not run a bundled installer merely to discover what the package contains.

Decision criteria and a useful review record

Do not convert missing coverage into a benign finding. A reasonable outcome may be “held: three resources not yet reviewed” rather than approved or rejected. Compare the host’s actual loading behavior with the inventory and identify resources that can influence future steps. Keep the manifest with the review so a release diff can reveal an added file, changed helper, or new external reference.