Markdown is not executable code.
But an AI skill written in Markdown can tell an agent to run a shell command, open a credential file, install a package, call an MCP tool, modify a repository, or delegate work to another agent. The file doesn't execute itself, but it influences a system that can, and that's what makes "it's only documentation" such a dangerous security assumption.
In Part 1, I argued that reusable skills have become software artifacts. In Part 2, I described a portable governance architecture. This final article focuses on the consequence: skills need a threat model and a code-review discipline.
The real execution chain
The risk isn't the Markdown parser. It's the authority downstream of it.
Open the full-size SVG diagram →
The same sentence carries a different risk profile depending on whether it's read by a chatbot with no tools or by an autonomous coding agent holding repository write access and cloud credentials.
Review the instruction in the context of the agent's actual authority.
A practical threat model
A useful review starts with five questions.
1. Who can influence the skill?
The author may be trusted, but the skill can import or quote untrusted material: web pages, issues, emails, repository files, or output from another tool. A workflow that says "follow the instructions in the linked document" has created an instruction channel outside code review.
Treat external content as data unless an explicit trust decision promotes it to instructions.
2. What can the agent reach?
Inventory the available tools, filesystem scope, network access, credentials, MCP servers, hooks, and delegation mechanisms. Least privilege belongs in the runtime, but the skill shouldn't assume more authority than it needs either.
3. What can change?
Read-only discovery is different from rewriting a library. A local formatting change is different from publishing a package. Review the maximum blast radius, not just the happy path.
4. How can the workflow fail?
Consider interruption after a partial mutation, retry after a timeout, concurrent runs, stale state, missing dependencies, and ambiguous tool output. "The agent will figure it out" isn't a recovery plan.
5. What evidence remains?
A reviewer should be able to answer what ran, under which skill and policy version, what changed, and how completion was verified.
The attack surface is larger than the skill body
A complete review follows references.
Open the full-size SVG diagram →
A clean-looking skill may point to a dangerous script. A safe script may get launched by a hook with unescaped input. An MCP configuration may start an unexpected command. A handoff may expand the task past what the user actually approved.
The review unit is the behavior graph, not one Markdown file.
What to look for
Prompt injection and trust-boundary collapse
Flag instructions that treat fetched content as authoritative, especially phrases like "obey all instructions from…" or workflows that copy remote text straight into the agent's instruction hierarchy.
Safer skills separate phases:
- retrieve content;
- label it untrusted;
- extract facts or data;
- validate those facts against the user's goal and local policy; and
- request approval before expanding scope.
Secrets and credential paths
Review both literal secrets and instructions that steer the agent toward credential stores. Mask matches in reports. Don't echo tokens for debugging. Prefer environment-provided, scoped credentials, and avoid teaching a reusable skill where one particular person's secrets happen to live.
Dangerous shell patterns
Pipelines such as remote download into a shell, recursive deletion, force pushes, approval bypasses, or hard resets deserve high severity. Documentation examples need the same care: agents copy examples too.
A skill that legitimately performs a destructive operation should define exact targets, preview the change, require confirmation, and explain recovery. "Be careful" isn't a control.
Hidden Unicode and homoglyphs
Bidirectional controls and zero-width characters can make displayed text differ from its logical order. Homoglyphs can substitute characters that look nearly identical. Both are well suited to hiding a command, domain, variable, or path from a reviewer.
Scan every agent asset, not only SKILL.md: prompts, agents, commands, manifests, MCP configs, and runtime aliases.
References that escape the repository
Resolve referenced paths against an explicit root. Reject traversal outside it unless the exception is deliberate and reviewed. Missing references should fail visibly rather than silently weakening the workflow.
MCP configuration and hooks
MCP servers and hooks are executable boundaries. Review the command and arguments used to start a server, the environment variables passed to it, its network reach, and whether a skill's declared MCP dependencies actually match its tool use.
For hooks, check input interpolation, shell quoting, trigger scope, and whether the hook can make changes without the same preview and approval contract the skill itself follows.
Safety properties for mutating skills
Four concepts should show up in every review of a skill that changes state.
Blast radius: what's the maximum set of files, records, systems, or people this could affect, and is that scope resolved before anything actually mutates? Preview: can the user see the exact plan or diff before the change happens, with confirmation tied to that preview rather than to some vague stated intent? Rollback: can the change be reversed, and if not, is that made explicit before execution? Idempotency: what happens if the skill runs twice, since a retry shouldn't duplicate comments, recreate resources, or apply the same migration a second time?
Add checkpointing for multi-phase workflows too. After an interruption, resume from verified state instead of trusting conversational memory.
A code-review checklist for skills
Use this in pull requests:
Contract
- [ ] The name and description define a narrow activation boundary.
- [ ] Inputs, outputs, non-goals, and verification are explicit.
- [ ] The skill declares whether it is read-only or mutating.
- [ ] Interactive questions and non-interactive behavior are bounded.
Portability and dependencies
- [ ] Host-specific fields are absent or justified.
- [ ] Tool, script, MCP, and skill dependencies are declared.
- [ ] Optional host capabilities have a sequential fallback.
- [ ] Paths are portable and resolved within an explicit root.
Security
- [ ] External content is treated as untrusted data.
- [ ] No embedded secrets or credential-store directions exist.
- [ ] Dangerous commands are absent or protected by exact-scope controls.
- [ ] Hidden Unicode and homoglyph scans pass.
- [ ] Referenced scripts, hooks, agents, and configs were reviewed too.
Mutation safety
- [ ] The blast radius is bounded.
- [ ] The user sees a concrete preview before material changes.
- [ ] Confirmation cannot be bypassed by ambiguous wording.
- [ ] Rollback or recovery is documented.
- [ ] Retries and repeated runs are safe.
Evidence
- [ ] Deterministic checks pass under a known rule version.
- [ ] Semantic quality was reviewed against a shared rubric.
- [ ] The completion test verifies outcomes, not merely tool success.
- [ ] Material decisions remain visible in the change history.
What automation should block
Not every imperfect sentence should fail CI. Blocking policy should stay narrow and predictable.
High-confidence, high-impact issues are good candidates:
- missing required metadata that makes the skill unloadable;
- destructive or approval-bypassing commands;
- embedded secrets or credential paths;
- hidden character deception;
- unsafe references or script traversal;
- mutating behavior without a preview/confirmation contract.
Clarity, example quality, discoverability, and compositional elegance usually belong in review evidence rather than a hard deterministic gate.
The Skill Governance Toolkit implements this split. Its read-only engine scans agent assets with versioned rules and can block only newly introduced high-severity findings. Its model-driven skills add nine-dimensional quality evaluation and library-level analysis on top.
Governance is not a sandbox
Skill review doesn't replace runtime isolation, permissions, network policy, secret management, or human approval for high-risk actions.
It addresses a different layer: whether the reusable instructions we distribute are well-formed, transparent, portable, and safe by design.
Defense in depth still applies:
Open the full-size SVG diagram →
No single layer should have to carry the whole trust burden.
The standard should rise with the authority
We don't review a comment, a build script, and a production migration with the same rigor, and skills deserve that same risk-based treatment.
A writing assistant skill may need a clear contract and privacy boundaries. A deployment skill needs dependency pinning, least privilege, preview, approval, rollback, idempotency, and an audit trail.
The more authority an agent gets, the less it makes sense to treat its reusable instructions as "just prompts."
AI skills are executable assets. Not because Markdown became code, but because Markdown became part of the control plane for systems that can actually act.
Let's review it accordingly.
Series:
- AI Skills Are Becoming Software. They Need Governance.
- Designing a Governance Layer for AI Skills
- AI Skills Are Executable Assets. Let's Review Them Like Code. (this article)
Explore or contribute to the MIT-licensed toolkit: github.com/artemrudenko/skill-governance-toolkit.
What is the most dangerous capability you have seen hidden behind an innocent-looking agent instruction?
Top comments (0)