feat(skills): Add agent skills

[mkmeral]

Description

This PR adds a new skills tool that implements support for Agent Skills - modular packages of specialized instructions that help AI agents perform specific tasks effectively.

What are Agent Skills?

Agent Skills are folders containing SKILL.md files with structured instructions. They follow the AgentSkills.io specification and enable:

• Progressive Disclosure: Load only skill metadata initially (~100 tokens), full instructions on demand
• Modular Knowledge: Package domain-specific expertise as reusable skills
• No Code Changes: Add/remove capabilities via markdown files

Tool Design

The tool follows the action-based pattern used by other tools (like mcp_client, memory, slack):

from strands import Agent
from strands_tools import skills

agent = Agent(tools=[skills])

# List available skills (auto-discovered from STRANDS_SKILLS_DIR)
agent.tool.skills(action="list")

# Use a skill - loads its instructions into conversation
agent.tool.skills(action="use", skill_name="code-reviewer")

# Load a resource file from a skill
agent.tool.skills(action="get_resource", skill_name="code-reviewer", resource_path="scripts/analyze.py")

Actions

Action	Description
list	Show all available skills with descriptions
use	Load a skill's full instructions (returned as tool result)
get_resource	Load a script/reference/asset file from a skill
list_resources	List all files available in a skill

Helper Function

The tool also provides a get_skills_prompt() helper for users who want proactive skill awareness in their agent's system prompt:

from strands import Agent
from strands_tools.skills import skills, get_skills_prompt

# Optional: Add skills to system prompt for proactive awareness
base_prompt = "You are a helpful assistant."
agent = Agent(
    tools=[skills],
    system_prompt=base_prompt + get_skills_prompt()
)

Design Decisions

1. Simple stateless design: Skills are loaded on demand and returned as tool results. No state tracking or system prompt modification - this matches how Anthropic's skills and AWS sample implementation work.

2. No activate/deactivate: These concepts don't exist in the AgentSkills.io spec. Skills are simply loaded when needed via conversation history.

3. Auto-discovery: Skills are automatically discovered from STRANDS_SKILLS_DIR (default: ./skills) on first use.

4. SKILL.md format: Follows AgentSkills.io spec with YAML frontmatter for metadata and markdown body for instructions.

SKILL.md Frontmatter Fields

The tool parses YAML frontmatter from SKILL.md files. Supported fields:

Field	Required	Description	Usage
name	Yes	Skill identifier (kebab-case, max 64 chars)	Used as the key for skill_name parameter
description	Yes	Brief description of the skill	Shown in list action output
license	No	License identifier (e.g., Apache-2.0)	Stored in metadata, not currently displayed
allowed-tools	No	Comma-separated list of tools the skill expects	Shown in list action output (informational only)

Example SKILL.md:

---
name: code-reviewer
description: Performs thorough code reviews with focus on security and best practices.
license: Apache-2.0
allowed-tools: file_read, shell
---

# Code Reviewer Instructions

Your detailed instructions here...

Note: The allowed-tools field is informational only - the tool doesn't enforce or validate tool availability. It's displayed to help users understand what tools a skill expects to use.

Skill Directory Structure

skills/
├── code-reviewer/
│   ├── SKILL.md              # Required: YAML frontmatter + instructions
│   ├── scripts/              # Optional: Executable code
│   │   └── analyze.py
│   └── references/           # Optional: Additional documentation
│       └── security.md
└── data-analyst/
    └── SKILL.md

Environment Variables

Variable	Default	Description
STRANDS_SKILLS_DIR	./skills	Directory containing skill folders

Related Issues

• [FEATURE] Add support for skills sdk-python#1181

Documentation PR

N/A - Documentation is included in README.md updates in this PR.

Type of Change

New Tool

Testing

• 16 unit tests covering all actions, error handling, auto-discovery, and get_skills_prompt helper
• All tests pass (python -m pytest tests/test_skills.py -v)
• Linting passes (ruff check src/strands_tools/skills.py tests/test_skills.py)

Test coverage includes:

• Skill listing (empty, non-existent, valid directories)
• Skill usage (valid, non-existent, missing parameters)
• Resource handling (list, get, path traversal protection)
• Error handling (invalid actions, missing required params)
• Auto-discovery from environment variable
• get_skills_prompt() helper function (XML output, empty directory, env var usage, cache sharing)

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[vivekghatala]

Thank you for working on this. I was thinking to pick this up as one of the consumer.

[ShotaOki]

I think this is an excellent pull request !
However, when I ran the steps below, I got an error. Will this be fixed?

1. pip install strands-agents strands-agents-tools
2. Replace strands-agent-tools to mkmeral:feature/agent-skills
3. Write the code “from strands_tools.skills import skills”
4. Run the code from step 2

[afarntrog]

This is great! Wondering if it should be vended as part of the core SDK instead of the tools repo.

[mkmeral]

@afarntrog strands-agents/docs#528 what do you think?

[tahitimoon]

This tool feels really great. I’ve been waiting for it for a long time and I’m wondering when it will be released.

[kevmyung]

Hi @mkmeral, nice work on this PR!

Just curious — since Level 1 metadata in the system prompt is essentially a prerequisite for the agent to discover and use skills at all, would it be worth having the SDK handle this automatically when skills is registered as a tool (e.g., via AgentInitializedEvent hook)? The current get_skills_prompt() approach works, but it feels like something the framework could take care of for the developer.