feat(skills): add agent skills as a plugin

[mkmeral]

Motivation

See design strands-agents/docs#528

This PR adds SkillsPlugin, a first-class plugin that brings Agent Skills support to Strands. It follows the spec's progressive disclosure model: lightweight metadata (name + description) is injected into the system prompt at startup, and full instructions are loaded on-demand when the agent activates a skill via a tool call. This keeps context usage low while giving agents access to rich, task-specific instructions when needed.

Public API Changes

New SkillsPlugin class and Skill dataclass, both exported from the top-level strands package:

from strands import Agent
from strands.plugins.skills import SkillsPlugin, Skill

# Load skills from filesystem (individual dirs or parent dirs)
plugin = SkillsPlugin(skills=["./skills/pdf-processing", "./skills/"])

# Or provide Skill instances directly
skill = Skill(name="my-skill", description="A custom skill", instructions="Do the thing")
plugin = SkillsPlugin(skills=[skill])

agent = Agent(plugins=[plugin])

The plugin registers a skills tool that the agent calls to activate a skill by name. When activated, the tool returns the full instructions along with metadata (allowed tools, compatibility, location) and a listing of available resource files (scripts/, references/, assets/) for filesystem-based skills.

Skills can be managed at runtime via a symmetric property and a resolution method:

# Direct replacement with Skill instances
plugin.available_skills = [skill_a, skill_b]

# Load and append from filesystem paths (resolves paths, Skill instances, or parent dirs)
plugin.load_skills(["./new-skills/", another_skill])

Skill metadata is injected into the system prompt as XML before each invocation, with special characters escaped:

<available_skills>
<skill>
<name>pdf-processing</name>
<description>Extract text and tables from PDF files.</description>
<location>/path/to/pdf-processing/SKILL.md</location>
</skill>
</available_skills>

The active skill selection is persisted to agent.state for session recovery.

Use Cases

• Skill libraries: Point the plugin at a directory of skills and let the agent pick the right one based on the user's request
• Dynamic specialization: Swap agent behavior at runtime without rebuilding prompts or agents
• Portable skills: Share skill directories across teams and agents using the Agent Skills standard format

Resolves: #1181

Documentation PR

TBD

Type of Change

New feature

Testing

• Manually tested using jupyter notebook and set of skills from anthropic/skills repository

• 100 unit tests covering the plugin, tool, XML generation/escaping, response formatting, resource listing, session persistence, and skill resolution

• 2 integration tests against a real Bedrock model: model-driven skill activation with codeword verification, and direct tool invocation with state persistence checks

• All existing tests (2145 total) continue to pass

• I ran hatch run prepare

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, or no new docs are needed
• 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.

[codecov]

Codecov Report

❌ Patch coverage is 92.35669% with 24 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/plugins/skills/agent_skills.py	87.34%	12 Missing and 9 partials ⚠️
src/strands/plugins/skills/skill.py	97.90%	2 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Follow-up Review: Latest Commit ✅

Good progress! The new changes address key feedback:

Changes in latest commit

• ✅ Changed name to class attribute (name = "agent_skills") - per Unshure's feedback
• ✅ Added skill activation tracking via _track_activated_skill()
• ✅ Added public get_activated_skills(agent) method for activation history
• ✅ Skills tracked in activation order (most recent last, no duplicates)

The activation tracking is a nice addition that partially addresses sanjolia's multi-skill concern - while only one skill is "active" at a time for instruction loading, the agent state now tracks the full history of activated skills.

Remaining items:

• Documentation PR still shows "TBD" - needs to be updated before merge per repository guidelines
• Consider if needs-api-review label should be added for this new public API

The implementation looks solid and ready for final approval once documentation is addressed.

[github-actions]

Assessment: Request Changes

The implementation is excellent and all technical feedback has been addressed. However, the PR description still shows "Documentation PR: TBD" which needs to be resolved before merge.

Review Summary

Technical Implementation: ✅ Ready

• Clean plugin architecture following repository patterns
• Comprehensive test coverage (unit + integration)
• Lenient validation per AgentSkills.io spec
• Proper XML escaping and error handling
• Skill activation tracking for session persistence

Blocking Item:

• Documentation PR: The PR description states "TBD" under Documentation PR. Per repository guidelines, either:
  1. Link to a documentation PR at https://github.com/strands-agents/docs/pull/...
  2. Provide justification why documentation updates are not required

Once the documentation requirement is addressed, this PR is ready to merge. Great work on iterating through the feedback! 🎉

[mehtarac]

don't block on docs /strands review

[Unshure]

Any reason we cant up the coverage in this pr? https://app.codecov.io/gh/strands-agents/sdk-python/pull/1755?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=strands-agents

[mkmeral]

/strands review

agent too noisy