A skill description such as "helps with audits" leaves an assistant to guess which audits, what input it needs, and when to use it. A specific description can answer those questions before the client loads the full instructions.
That is where a useful Agent Skill begins. The package needs a clear job, and a supporting client needs a way to locate it. Publishing the files solves only part of the problem: the client still has to decide whether to load and trust them.
The package starts with SKILL.md
The Agent Skills specification defines the package around SKILL.md. At minimum, a skill directory contains that file. Its frontmatter requires name and description; supporting scripts, references, and assets directories are recommended organization patterns rather than required package contents (Agent Skills, "Agent Skills Specification").
Use those fields to distinguish the skill from other packages. The name identifies it; the description should make its intended job clear before the client reads the longer instructions.
MachineRead's source package follows that pattern. The machineread-audit skill declares its name, describes the free Essentials audit surface, gives concrete trigger phrases, and points to references plus a helper script. The package README records the same layout: SKILL.md, reference files, and scripts/run_audit.py.
Write the description for a decision
The Agent Skills specification describes progressive disclosure: a client can consider the name and description before loading the full instructions, then retrieve supporting resources as needed (Agent Skills, "Agent Skills Specification"). That makes the short description an important part of the package.
For an audit skill, useful wording would identify public website audits, a URL as input, the available report, and when a different tool is needed. Put detailed API instructions in the body rather than trying to fit the entire manual into the description. A client should be able to distinguish the skill from a security audit or a financial audit without loading every reference.
Network discovery is a separate layer
A local skill package and a network discovery index solve different problems. The package tells a client what to do after it has the skill. The index gives publishers a place to list skill artifacts and file digests for clients that choose to look there.
Cloudflare's agent-skills-discovery-rfc repository is useful evidence of that second idea, but only as a draft proposal. Its README calls v0.1.0 an initial draft and describes a proposed /.well-known/agent-skills/index.json with schema versioning, artifact types, and raw-byte SHA-256 digests (Cloudflare). The proposal should not be described as a finalized universal standard.
The well-known path also should not be overread. A URL can make a file easier to locate. It does not prove that clients probe the path, trust the publisher, download an archive, activate a skill, run a helper, or enforce a digest.
How to read the finding
Treat an Agent Skills finding as a pointer to inspect, not a proof of adoption. Open the index. Check whether the listed URL resolves in the environment you care about. Hash the returned bytes if integrity matters. Read the description and decide whether it names a real task, trigger, input, output, and caveat boundary.
If the skill includes helper code, review it before running it. If it includes references, check whether they explain the API contract or only repeat marketing language. A skill that is easy to discover but vague after loading still leaves the agent guessing.
Inspect the package before using it
MachineRead documents its own machineread-audit package and discovery index in the Agent Integration guide. That publishing surface is separate from the target-site checks that look for Agent Skills indexes on other sites.
A catalog entry may include file digests. Comparing downloaded bytes with a listed digest can detect a mismatch, but it does not establish that the publisher is trustworthy or that helper code is safe. Read the instructions and inspect any executable files before allowing a client to use them.
Update the catalog with the package. A correct description is little help if a required reference has moved. Test the published URLs and use a client that supports the package format; a static file check cannot establish client compatibility.
Works Cited
Agent Skills. "Agent Skills Specification." Agent Skills, https://agentskills.io/specification. Accessed 9 Sept. 2026.
Cloudflare. "agent-skills-discovery-rfc." GitHub, https://github.com/cloudflare/agent-skills-discovery-rfc. Accessed 9 Sept. 2026.
See also
- Methodology reference - separates repository/static checks from runtime guarantees
- Using MachineRead from an MCP client - another place where client behavior and target behavior must stay separate
- What an A2A agent card is for - a related discovery-document boundary