Docs
Scannednpx machina-cli add skill aws-samples/sample-strands-agents-agentskills/docs --openclawEnglish | 한국어
SKILL
A skill is essentially a folder containing a SKILL.md file. This file contains metadata (at minimum, a name and description) and instructions that tell an agent how to perform a specific task. Skills may also include scripts, templates, and reference materials.
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
How SKILL Works
Skills use Progressive Disclosure to efficiently manage context.
- Discovery: The agent loads only the name and description of each available skill at startup. This is the minimum information needed to determine when a skill might be relevant.
- Activation: When a task matches a skill's description, the agent reads the full instructions from the SKILL.md file into context.
- Execution: The agent follows the instructions, loading referenced files or executing bundled code as needed.
SKILL.md Format
All skills start with a SKILL.md file containing YAML frontmatter and Markdown instructions.
---
name: web-research
description: Perform comprehensive research through web search and analysis
allowed-tools: WebFetch, Grep
license: MIT
---
# instructions
When using this Skill...
## Step 1: Search
...
Required Fields
name: kebab-case format (e.g.,web-research)description: What the Skill does and when to use it
Optional Fields
license: Skill licensecompatibility: Compatibility informationallowed-tools: Tool patterns the Skill can usemetadata: Custom key-value pairs
Source
git clone https://github.com/aws-samples/sample-strands-agents-agentskills/blob/main/docs/WHAT_IS_SKILL.mdView on GitHub Overview
Docs explains what a Skill is and how it is organized. A Skill is a folder containing a SKILL.md with metadata and instructions to perform a task, plus optional scripts, templates, and references. It uses Progressive Disclosure to keep startup light and load full instructions when needed.
How This Skill Works
During startup, the agent loads only the name and description for each Skill. When a task matches a Skill's description, the agent reads the full SKILL.md into context and follows its instructions, loading any referenced files or bundled code as required.
When to Use It
- Wiring new modular tasks into the agent catalog
- Optimizing startup time by loading only metadata first
- Activating full instructions only after a task matches a Skill
- Including optional assets (scripts, references, templates) to support execution
- Auditing Skill structure and metadata for consistency
Quick Start
- Step 1: Create a folder (e.g., my-skill) and add SKILL.md with required frontmatter (name and description)
- Step 2: Add the task instructions and optional folders (scripts/, references/, assets/) as needed
- Step 3: Start the agent and verify discovery loads only metadata, then trigger a matching task to test full activation
Best Practices
- Write a clear name and concise description in the frontmatter
- Use kebab-case for the name field
- Place executable code in scripts/, templates in assets/, and references in references/
- List license, compatibility, and allowed-tools when applicable
- Test discovery and activation with representative tasks
Example Use Cases
- web-research: perform comprehensive web searches and analysis
- data-cleanup: normalize, deduplicate, and format datasets
- report-generation: compile findings into formal reports
- email-notify: draft and send status update emails
- incident-checklist: run safety and compliance checks
