An Agent Skill is a reusable operating method
A Skill tells an agent how to approach a recognisable class of work: when the procedure applies, which steps matter, which evidence to preserve, and what a good result looks like. The open Agent Skills specification defines a directory centred on a required SKILL.md file, with optional scripts, references, and assets.
That structure separates durable procedural knowledge from the user’s immediate prompt. It also lets a runtime show only a Skill’s name and description during discovery, then load the full instructions when the task actually needs them.
What belongs inside a Skill bundle?
| Element | Role | Enterprise consideration |
|---|---|---|
SKILL.md | Metadata and the primary procedure | Review ownership, allowed capabilities, and change history |
references/ | Detailed material loaded when needed | Classify source sensitivity and freshness |
assets/ | Templates or files used in outputs | Check licensing and prevent hidden sensitive data |
scripts/ | Optional helper code for supporting clients | Do not assume execution; apply software supply-chain controls |
evals/ | Representative cases and expected behaviour | Measure triggering, output quality, and safety boundaries |
VDF runtime boundary. Bundled scripts can be stored and read as part of a Skill package, but the current VDF AI environment does not execute them.
Progressive disclosure keeps specialised context focused
Loading every procedure into every conversation would consume context and make relevant instructions compete with unrelated ones. A progressive system exposes Skills in layers:
- Discovery: list compact names, descriptions, and locations.
- Activation: load the selected
SKILL.mdwhen its procedure is relevant. - Supporting context: read a bundled reference or asset only when a step needs it.
- Execution: call separately authorised tools under the runtime’s policy.
- Evidence: record activation and file-read events for inspection.
This makes the Skill both discoverable and economical: enough information is available to choose it, while deeper material stays out of the active context until required.
Agent Skills vs prompts, tools, MCP, agents, and workflows
| Concept | Primary responsibility | Useful mental model |
|---|---|---|
| Prompt | Express the current request and context | What needs to happen now |
| Agent | Define identity, model, role, and operating limits | Who is doing the work |
| Skill | Supply a reusable procedure and supporting knowledge | How the specialist works |
| Tool | Perform a bounded capability or external action | What the specialist can use |
| MCP | Expose tools and context through a protocol | How capabilities are connected |
| Network | Coordinate several model-driven stages | How specialists work together |
Move from a useful instruction to a governed asset
A production Skill needs clear ownership, validation, permissions, representative tests, and a controlled change history.
- 01
Create or import
Start in the editor, upload a Skill ZIP, or import supported skill content from an Agent Plugin.
- 02
Validate
Check the bundle structure and metadata, then resolve every reported issue before publishing.
- 03
Bind permissions
Assign the Skill to an agent and separately grant only the tools its procedure can use.
- 04
Test
Try explicit invocation and representative requests, then inspect activation and file-read events.
- 05
Version and operate
Preserve a reviewable snapshot, monitor usage, and update the Skill as the workflow changes.
A non-proprietary SKILL.md starting point
---
name: source-check
description: Check a factual claim against supplied sources.
metadata:
version: "1.0"
allowed-tools: web_search web_crawler
---
# Source check
Use this Skill when a user asks whether a current factual claim is true.
1. Clarify the exact claim and relevant date.
2. Prefer primary or authoritative sources.
3. Separate sourced facts from inference.
4. Link evidence beside the claim it supports.
5. State what remains uncertain.The example is intentionally small. A strong description makes activation easier, while the procedure provides only the judgement needed to produce a consistent outcome.
Four controls should remain outside the Skill text
Permissions
Grant tool and connector access through enforceable platform policy, never through an instruction claiming access.
Approvals
Use explicit runtime approval gates for high-impact changes instead of relying only on polite wording.
Versions
Preserve snapshots so reviewers can connect an observed outcome to the procedure that produced it.
Telemetry
Record availability, activation, supporting-file reads, and output context without exposing confidential content.
A shared format is a baseline, not a universal runtime guarantee
The specification provides common structure and naming rules. Clients may still differ in supported metadata, tool syntax, automatic activation, file handling, and script execution. Exported Skills should therefore be validated and tested in the destination client before teams claim behavioural equivalence.
Common Agent Skills questions
What is an Agent Skill?
An Agent Skill is a directory containing a required SKILL.md file and optional supporting resources. It packages a repeatable method that an AI agent can discover and load when a task requires it.
Is an Agent Skill the same as a prompt?
No. A prompt is the immediate request or conversation context. A Skill is a maintained, reusable asset with metadata, instructions, and optional bundled files.
Do Agent Skills replace MCP or tools?
No. MCP can expose capabilities and context, while tools perform actions. A Skill describes how an agent should combine judgement, context, and permitted capabilities to complete a job.
Are Agent Skills portable?
The open directory format provides a shared structural baseline, but clients can support different metadata and runtime behaviours. Test compatibility before claiming that a Skill works unchanged in another environment.
Primary references
- Agent Skills specification — directory structure, metadata, progressive disclosure, and validation rules.
- Google Search guidance for AI features — crawlability, original content, and clear page structure.
- VDF AI Agent Skills documentation — product-specific creation, binding, testing, and runtime behaviour.