Skip to content
Back to search

sample-strands-agents-agentskills

Agent Skills implementation for Strands Agents SDK

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aws-samples--sample-strands-agents-agentskills/badge.svg)](/listings/aws-samples--sample-strands-agents-agentskills)

HTML

<a href="/listings/aws-samples--sample-strands-agents-agentskills"><img src="/api/listings/aws-samples--sample-strands-agents-agentskills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

System Requirements

- Python 3.13 or higher - Strands Agents SDK 1.0.0 or higher - Strands Agents Tools 0.2.0 or higher

Installation

# Using requirements.txt
pip install -r requirements.txt

# Package installation (development mode)
pip install -e .

Code Samples

Pattern 1: File-based (Filesystem-Based)

from agentskills import discover_skills, generate_skills_prompt
from strands import Agent
from strands_tools import file_read

# 1. Skill discovery (Phase 1: load only metadata)
skills = discover_skills("./skills")

# 2. Generate system prompt (include only skill metadata)
base_prompt = "You are a helpful AI assistant."
skills_prompt = generate_skills_prompt(skills)
full_prompt = base_prompt + "\n\n" + skills_prompt

# 3. Create Agent
agent = Agent(
    system_prompt=full_prompt,
    tools=[file_read],  # LLM reads SKILL.md when needed
    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
)

# 4. Progressive Disclosure in action:
# Phase 1: metadata in system prompt
# Phase 2: LLM reads SKILL.md via file_read
# Phase 3: LLM reads resources via file_read
response = await agent.stream_async("Research Physical AI")

Pattern 2: Tool-based

from agentskills import discover_skills, create_skill_tool, generate_skills_prompt
from strands import Agent
from strands_tools import file_read

# 1. Skill discovery (Phase 1: load only metadata)
skills = discover_skills("./skills")

# 2. Create skill tool
skill_tool = create_skill_tool(skills, "./skills")

# 3. Create agent with system prompt and skill tool
agent = Agent(
    system_prompt=base_prompt + "\n\n" + generate_skills_prompt(skills),
    tools=[skill_tool, file_read],  # skill + file_read combination
    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
)

# Progressive Disclosure in action:
# Phase 1: metadata in system prompt
# Phase 2: skill(skill_name="web-research")
# Phase 3: read resources via file_read
response = await agent.stream_async("Research Physical AI")

Pattern 3: Meta-Tool (Agent as Tool)

from agentskills import discover_skills, create_skill_agent_tool, generate_skills_prompt
from strands import Agent
from strands_tools import file_read, file_write, shell

# 1. Skill discovery (Phase 1)
skills = discover_skills("./skills")

# 2. Create meta-tool (Agent as Tool pattern)
meta_tool = create_skill_agent_tool(
    skills,
    "./skills",
    additional_tools=[file_read, file_write, shell]  # Tools to provide to Sub-agent
)

# 3. Generate system prompt
base_prompt = """You are a helpful AI assistant with specialized skills.
Use the use_skill tool to execute skills in isolated sub-agents."""

full_prompt = base_prompt + "\n\n" + generate_skills_prompt(skills)

# 4. Create main agent
agent = Agent(
    system_prompt=full_prompt,
    tools=[meta_tool], # Sub-agent runs in isolation
    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
)

# Progressive Disclosure + Meta-Tool:
# Phase 1: metadata in system prompt
# Phase 2: use_skill(skill_name, request) call
# Phase 3: Sub-agent receives SKILL.md as system prompt and executes
response = await agent.stream_async("Research Physical AI")

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 419 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>
  3. Agent Skills for Strands Agents SDK
  4. </h1>
  5. <p>
  6. <a href="./README.md">English</a>
  7. | <a href="./README_kr.md">한국어</a>
  8. </p>
  9. </div>
  10. **Basic architecture for using Agent Skills in Strands Agents SDK**
  11. This package implements the [AgentSkills.io](https://agentskills.io) standard for use with Strands Agents SDK. It provides a reusable and extensible Agent Skills system designed based on the Progressive Disclosure principle.
  12. ## 🎥 Demo
  13. <div align="center">
  14. <a href="https://youtu.be/aq5Ilt3uS38">
  15. <img src="https://img.youtube.com/vi/aq5Ilt3uS38/0.jpg" alt="Demo Video" width="400"/>
  16. </a>
  17. </div>
  18. ## 📊 Skill Outputs
  19. <table>
  20. <tr>
  21. <td align="center">
  22. <img src="docs/sample/result_docx.png" alt="DOCX Result" width="400"/>
  23. <br/>
  24. <strong>[skills/docx] Output</strong>
  25. </td>
  26. <td align="center">
  27. <img src="docs/sample/result_pptx.png" alt="PPTX Result" width="400"/>
  28. <br/>
  29. <strong>[skills/pptx] Output</strong>
  30. </td>
  31. </tr>
  32. </table>
  33. ## 🎯 Project Introduction
  34. ### What are Agent Skills?
  35. Agent Skills are modular capabilities that give AI Agents specialized abilities. Each Skill packages domain-specific knowledge (web research, file processing, etc.), workflows, and best practices to transform a general-purpose Agent into a domain expert.
  36. ### Why are Agent Skills needed?
  37. **Limitations of traditional tool-based approaches:**
  38. - **Token inefficiency**: All tool specifications are always loaded into context
  39. - **Complexity increase**: As tools increase, Agent decision complexity grows exponentially
  40. - **Lack of reusability**: Difficult to reuse specialized knowledge in other projects
  41. **Agent Skills solutions:**
  42. - **Progressive Disclosure**: Load only necessary information when needed
  43. - **Modularization**: Manage as independent Skills for improved reusability
  44. - **Specialization**: Encapsulate complex multi-step tasks as a single Skill
  45. ### Core Philosophy
  46. This implementation follows these core principles:
  47. #### 1. Standard Compliance
  48. Fully implements the [AgentSkills.io](https://agentskills.io) standard:
  49. - SKILL.md format (YAML frontmatter + Markdown)
  50. - Required fields: `name`, `description`
  51. - Optional fields: `license`, `compatibility`, `allowed-tools`, `metadata`
  52. - Name validation (kebab-case, max 64 characters)
  53. - Progressive disclosure pattern
  54. - Security (path traversal prevention, file size limits)
  55. > For SKILL documentation, see [WHAT_IS_SKILL.md](./docs/WHAT_IS_SKILL.md).
  56. #### 2. Progressive Disclosure Implementation
  57. Implements **Progressive Disclosure** following AgentSkills.io's 3-phase loading pattern. Load minimal metadata first, and full content only when needed:
  58. - **Phase 1 - Metadata (~100 tokens/skill)**: Load only Skill name and description during Discovery
  59. - **Phase 2 - Instructions (<5000 tokens)**: Load SKILL.md instructions when Skill is activated
  60. - **Phase 3 - Resources (as needed)**: Load resource files (`scripts/`, `references/`, `assets/`) only when needed
  61. **Token efficiency:**
  62. | Phase | Timing | Content | Tokens |
  63. |-------|--------|---------|--------|
  64. | 1 | Startup | All skill metadata | ~100/skill |
  65. | 2 | Activation | Single skill instructions | <5000 |
  66. | 3 | As needed | Individual resource files | Variable |
  67. #### 3. Security
  68. - **Path validation**: Prevents directory traversal attacks
  69. - **File size limits**: Prevents loading large files (max 10MB)
  70. - **Strict validation**: Enforces Agent Skills standard
  71. - **Clear errors**: Provides clear feedback on failure
  72. #### 4. Skills as Meta-Tools
  73. Skills are not executable code. Skills are:
  74. - **Prompt templates**: Domain-specific instructions
  75. - **Single tool pattern**: One Meta-tool manages all skills
  76. - **LLM-based selection**: Agent naturally selects appropriate skill
  77. - **Context expansion**: Skill injects specialized instructions into agent context
  78. ---
  79. ## 🔑 Core: 3 Implementation Patterns
  80. This package provides **3 implementation patterns** for using Agent Skills in Strands Agents SDK:
  81. ```mermaid
  82. flowchart TB
  83. subgraph "Agent Skills Implementation Patterns"
  84. direction TB
  85. P1["`**Pattern 1: File-based**
  86. LLM reads SKILL.md directly via file_read
  87. Most natural approach`"]
  88. P2["`**Pattern 2: Tool-based**
  89. Load Instructions via skill() tool
  90. Explicit skill activation`"]
  91. P3["`**Pattern 3: Meta-Tool (Agent as Tool)**
  92. Execute isolated Sub-agent via use_skill()
  93. Complete context separation`"]
  94. end
  95. P1 --> Result1["`Agent reads files directly
  96. ✓ Most natural
  97. ✓ Flexible access`"]
  98. P2 --> Result2["`Inject into Agent context
  99. ✓ Structured approach
  100. ✓ Easy token tracking`"]
  101. P3 --> Result3["`Independent Sub-agent execution
  102. ✓ Complete isolation
  103. ✓ Suitable for complex Skills`"]
  104. style P1 fill:#e8f5e9
  105. style P2 fill:#e3f2fd
  106. style P3 fill:#fff3e0
  107. ```
  108. **Pattern 1: File-based**
  109. : LLM reads files directly. Most flexible and token-efficient.
  110. **Pattern 2: Tool-based**
  111. : Explicitly load instructions via `skill` tool. Use when **structured approach** is needed.
  112. **Pattern 3: Meta-Tool (Agent as Tool)**
  113. : Meta-Tool approach where each Skill runs in an isolated Sub-agent as a tool.
  114. - **Complete isolation**: Each Skill runs in an independent Sub-agent (as a tool)
  115. - **Explicit control**: Skill execution is clearly visible
  116. - **Context independence**: Separation between Main agent and Sub-agent contexts
  117. - **Tool restrictions**: Explicitly specify tools to provide per Skill
  118. #### Pattern Comparison
  119. | Aspect | File-based | Tool-based | Meta-Tool |
  120. |:-------|:-----------|:-----------|:----------|
  121. | **Execution method** | LLM reads files directly | Inject into context | Isolated Sub-agent |
  122. | **Context isolation** | ❌ Shared | ❌ Shared | ✅ Complete isolation |
  123. | **Flexibility** | ✅ High | ⚠️ Medium | ⚠️ Low |
  124. | **Token tracking** | ⚠️ Difficult | ✅ Easy | ✅ Easy |
  125. | **Complexity** | ✅ Low | ⚠️ Medium | ⚠️ High |
  126. | **Recommended use** | General cases | When explicit control needed | Complex isolated execution |
  127. > 💡 **Selection Guide**
  128. > - **Inline Mode (Pattern 1, 2)** — Choose for simple workflows, natural LLM skill selection, lightweight implementation
  129. > - **Multi-Agent Mode (Pattern 3)** — Choose when Skill isolation, explicit control, per-Skill tool separation, or usage tracking is needed
  130. ### Data Flow of 3 Patterns
  131. ```mermaid
  132. flowchart TD
  133. Start([skills_dir<br/>├── skill-a<br/>└── skill-b]) --> Discover[discover_skills<br/>load_metadata]
  134. Discover --> Props["SkillProperties<br/>- name, description<br/>- path, skill_dir"]
  135. Props --> Prompt[generate_skills_prompt]
  136. Prompt --> SysPrompt["System Prompt<br/>Only skill metadata<br/>~100 tokens/skill"]
  137. SysPrompt --> Agent["Main Agent created"]
  138. UserReq["User request"] --> Agent
  139. Agent --> Pattern{Implementation pattern?}
  140. Pattern -->|"Pattern 1: File-based"| FileRead1["file_read call<br/>LLM reads SKILL.md directly"]
  141. FileRead1 -.-> FileReadRes["(optional) Read Resources via file_read"]
  142. Pattern -->|"Pattern 2: Tool-based"| SkillTool["skill() call<br/>load_instructions"]
  143. SkillTool --> InstBody["Add Instructions to<br/>Agent context"]
  144. InstBody -.-> FileReadRes
  145. FileReadRes --> Response
  146. Pattern -->|"Pattern 3: Meta-Tool"| UseSkill["use_skill() call"]
  147. UseSkill --> SubAgentCreate
  148. subgraph SubAgentBox["Sub-agent (isolated execution environment)"]
  149. SubAgentCreate["Sub-agent created"]
  150. SubAgentCreate --> LoadSkill["Load SKILL.md<br/>→ system_prompt"]
  151. LoadSkill -.-> FileReadRes3["(optional) Read Resources via file_read"]
  152. FileReadRes3 --> SubExec["Execute and generate results"]
  153. end
  154. SubExec --> ReturnMain["Return results to<br/>Main Agent"]
  155. ReturnMain --> Response
  156. Response[Agent generates final response]
  157. style Start fill:#e1f5ff
  158. style Props fill:#fff4e1
  159. style SysPrompt fill:#fff4e1
  160. style Agent fill:#e8f5e9
  161. style Pattern fill:#f5f5f5
  162. style FileRead1 fill:#c8e6c9
  163. style SkillTool fill:#bbdefb
  164. style InstBody fill:#bbdefb
  165. style FileReadRes fill:#f5f5f5,stroke-dasharray:5 5
  166. style UseSkill fill:#ffe0b2
  167. style SubAgentBox fill:#fff8e1,stroke:#ff9800,stroke-width:2px
  168. style SubAgentCreate fill:#ffe0b2
  169. style LoadSkill fill:#ffe0b2
  170. style FileReadRes3 fill:#ffe0b2,stroke-dasharray:5 5
  171. style SubExec fill:#ffe0b2
  172. style ReturnMain fill:#ffe0b2
  173. style Response fill:#e8f5e9
  174. ```
  175. ---
  176. ## Architecture
  177. ### Module Structure
  178. ```
  179. agentskills/
  180. ├── __init__.py # Public API
  181. ├── models.py # SkillProperties (Phase 1 metadata)
  182. ├── parser.py # load_metadata, load_instructions, load_resource
  183. ├── validator.py # AgentSkills.io standard validation
  184. ├── discovery.py # discover_skills (skill scanning)
  185. ├── tool.py # create_skill_tool (Pattern 2: Tool-based)
  186. ├── agent_tool.py # create_skill_agent_tool (Pattern 3: Meta-Tool)
  187. ├── prompt.py # generate_skills_prompt (system prompt generation)
  188. └── errors.py # Exception hierarchy
  189. ```
  190. > For core API information, see [API.md](./docs/API.md).
  191. ---
  192. ## Quick Start
  193. ### System Requirements
  194. - Python 3.13 or higher
  195. - Strands Agents SDK 1.0.0 or higher
  196. - Strands Agents Tools 0.2.0 or higher
  197. ### Installation
  198. ```bash
  199. # Using requirements.txt
  200. pip install -r requirements.txt
  201. # Package installation (development mode)
  202. pip install -e .
  203. ```
  204. ### Code Samples
  205. #### Pattern 1: File-based (Filesystem-Based)
  206. ```python
  207. from agentskills import discover_skills, generate_skills_prompt
  208. from strands import Agent
  209. from strands_tools import file_read
  210. # 1. Skill discovery (Phase 1: load only metadata)
  211. skills = discover_skills("./skills")
  212. # 2. Generate system prompt (include only skill metadata)
  213. base_prompt = "You are a helpful AI assistant."
  214. skills_prompt = generate_skills_prompt(skills)
  215. full_prompt = base_prompt + "\n\n" + skills_prompt
  216. # 3. Create Agent
  217. agent = Agent(
  218. system_prompt=full_prompt,
  219. tools=[file_read], # LLM reads SKILL.md when needed
  220. model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
  221. )
  222. # 4. Progressive Disclosure in action:
  223. # Phase 1: metadata in system prompt
  224. # Phase 2: LLM reads SKILL.md via file_read
  225. # Phase 3: LLM reads resources via file_read
  226. response = await agent.stream_async("Research Physical AI")
  227. ```
  228. #### Pattern 2: Tool-based
  229. ```python
  230. from agentskills import discover_skills, create_skill_tool, generate_skills_prompt
  231. from strands import Agent
  232. from strands_tools import file_read
  233. # 1. Skill discovery (Phase 1: load only metadata)
  234. skills = discover_skills("./skills")
  235. # 2. Create skill tool
  236. skill_tool = create_skill_tool(skills, "./skills")
  237. # 3. Create agent with system prompt and skill tool
  238. agent = Agent(
  239. system_prompt=base_prompt + "\n\n" + generate_skills_prompt(skills),
  240. tools=[skill_tool, file_read], # skill + file_read combination
  241. model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
  242. )
  243. # Progressive Disclosure in action:
  244. # Phase 1: metadata in system prompt
  245. # Phase 2: skill(skill_name="web-research")
  246. # Phase 3: read resources via file_read
  247. response = await agent.stream_async("Research Physical AI")
  248. ```
  249. #### Pattern 3: Meta-Tool (Agent as Tool)
  250. ```python
  251. from agentskills import discover_skills, create_skill_agent_tool, generate_skills_prompt
  252. from strands import Agent
  253. from strands_tools import file_read, file_write, shell
  254. # 1. Skill discovery (Phase 1)
  255. skills = discover_skills("./skills")
  256. # 2. Create meta-tool (Agent as Tool pattern)
  257. meta_tool = create_skill_agent_tool(
  258. skills,
  259. "./skills",
  260. additional_tools=[file_read, file_write, shell] # Tools to provide to Sub-agent
  261. )
  262. # 3. Generate system prompt
  263. base_prompt = """You are a helpful AI assistant with specialized skills.
  264. Use the use_skill tool to execute skills in isolated sub-agents."""
  265. full_prompt = base_prompt + "\n\n" + generate_skills_prompt(skills)
  266. # 4. Create main agent
  267. agent = Agent(
  268. system_prompt=full_prompt,
  269. tools=[meta_tool], # Sub-agent runs in isolation
  270. model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
  271. )
  272. # Progressive Disclosure + Meta-Tool:
  273. # Phase 1: metadata in system prompt
  274. # Phase 2: use_skill(skill_name, request) call
  275. # Phase 3: Sub-agent receives SKILL.md as system prompt and executes
  276. response = await agent.stream_async("Research Physical AI")
  277. ```
  278. ---
  279. ## Examples
  280. Complete examples are available in [examples/](examples/):
  281. - **[1-discovery_skills.py](examples/1-discovery_skills.py)** - Pattern 1: File-based approach
  282. - LLM directly reads SKILL.md files using `file_read` tool
  283. - Naturally performs Progressive Disclosure Phase 1-2-3
  284. - **[2-skill_tool_with_progressive_disclosure.py](examples/2-skill_tool_with_progressive_disclosure.py)** - Pattern 2: Tool-based approach
  285. - Load instructions using `skill` tool
  286. - Visually track token usage for Phase 1-2
  287. - **[3-skill_agent_tool.py](examples/3-skill_agent_tool.py)** - Pattern 3: Meta-Tool approach (Agent as Tool)
  288. - Each Skill runs in an isolated Sub-agent
  289. - Complete context separation and independent execution
  290. - **[4-streamlit_prompt_simulation.py](examples/4-streamlit_prompt_simulation.py)** - Streamlit-based Progressive Disclosure visualization
  291. - Visually check token usage and prompt status by phase
  292. - Simulate Skill activation and Resource loading
  293. - **[5-streamlit_strands_integration.py](examples/5-streamlit_strands_integration.py)** - Streamlit-based comparison demo of 3 patterns
  294. - Real-time comparison of File-based, Tool-based, Meta-Tool modes
  295. - Live execution using actual Strands Agents SDK
  296. For detailed example descriptions, see [examples/README.md](examples/README.md).
  297. ---
  298. ## Contributors
  299. - **Yoojung Lee** | [LinkedIn](https://www.linkedin.com/in/yoo-lee) | [GitHub](https://github.com/hi-space) | AWS AI/ML Specialist SA
  300. ## Security
  301. See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
  302. ## License
  303. This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.
  304. ## References
  305. - [Agent Skills Official Documentation](https://agentskills.io)
  306. - [Anthropic's Public Skills](https://github.com/anthropics/skills)
  307. - [Claude's Agent Skills Usage](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview)
  308. - [Agent Skills Best Practices](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/best-practices)
  309. - [Strands Agents SDK Official Documentation](https://strandsagents.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.