Skip to content

microsoft/amplifier-module-tool-skills

BranchesTags

Repository files navigation

Amplifier Skills Tool Module

Modular capability that adds skill-based domain knowledge loading to Amplifier bundles.

Overview

This module provides a progressive disclosure knowledge system for Amplifier agents. Skills are reusable knowledge packages that provide specialized expertise, workflows, and best practices following the Anthropic Skills format.

What You Get:

  • 🛠️ load_skill tool - Load domain knowledge from skill packages
  • 👁️ Visibility hook - Skills automatically shown to agent (no need to list first)
  • 📚 Multi-source support - Load skills from multiple directories
  • 🔄 Progressive disclosure - Three levels of knowledge depth

Progressive Disclosure Levels:

  • Level 1 (Metadata): Name + description (~100 tokens) - Always visible
  • Level 2 (Content): Full markdown body (~1-5k tokens) - Loaded on demand
  • Level 3 (References): Additional files (0 tokens until accessed)

Prerequisites

  • Python 3.11+
  • UV - Fast Python package manager

Installing UV

# macOS/Linux/WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

Recommended: Include the Behavior

Add skills capability to your bundle by including the behavior:

---
bundle:
  name: my-bundle
  version: 1.0.0
  description: My custom bundle with skills support

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
  - bundle: git+https://github.com/microsoft/amplifier-module-tool-skills@main#subdirectory=behaviors/skills.yaml
---

# Your bundle instructions...

What this gives you:

  • ✅ Tool + hook configured correctly together
  • ✅ Default skills directories (.amplifier/skills/, ~/.amplifier/skills/)
  • ✅ Visibility enabled (skills shown automatically to agent)
  • ✅ Clean dependency chain (no redundant includes)

Why this pattern?

  • You control your foundation version
  • Explicit about what capabilities you're adding
  • Gets both tool + hook working together

Alternative: Standalone Bundle

You can also use the complete skills bundle directly:

# Add the bundle
amplifier bundle add git+https://github.com/microsoft/amplifier-module-tool-skills@main

# Use it
amplifier bundle use skills
amplifier run "List available skills"

Note: The standalone bundle includes foundation and is useful for testing or quick experimentation, but the behavior inclusion pattern is recommended for production bundles.

Quick Start

1. Add Skills to Your Bundle

# your-bundle.md
includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
  - bundle: git+https://github.com/microsoft/amplifier-module-tool-skills@main#subdirectory=behaviors/skills.yaml

2. Create Skills Directory

mkdir -p .amplifier/skills

3. Use Your Bundle

amplifier bundle use your-bundle.md
amplifier run "What skills are available?"

The agent will see available skills automatically - no need to call load_skill(list=true) first!

4. Optional: Add Anthropic Skills Library

# Clone Anthropic's skills repository
git clone https://github.com/anthropics/skills ~/anthropic-skills

# Configure in settings.yaml (see Configuration section)

Configuration

Global Configuration (Recommended)

Add to ~/.amplifier/settings.yaml to make skills available to all bundles:

# Module source
sources:
  tool-skills: git+https://github.com/microsoft/amplifier-module-tool-skills@main

# Skills directories - applies to all bundles
skills:
  dirs:
    - ~/anthropic-skills/skills  # Optional: Anthropic's skills collection
    - ~/.amplifier/skills         # User-specific skills

Project-Specific Configuration

Add to .amplifier/settings.local.yaml for project-only skills:

skills:
  dirs:
    - .amplifier/skills  # Project-specific skills (merged with global)

Bundle-Level Override

Override skills directories in your bundle (if needed):

# In your bundle YAML frontmatter
tools:
  - module: tool-skills
    config:
      skills_dirs:
        - .amplifier/skills          # Project skills
        - ~/anthropic-skills/skills  # Anthropic library
        - ~/my-custom-skills         # Your skills
      visibility:
        enabled: true                # Show skills automatically (default: true)
        max_skills_visible: 50       # Limit for large collections (default: 50)

Configuration Priority

  1. Bundle config (skills_dirs in tool config) - highest priority
  2. Settings.yaml (skills.dirs in global/project settings) - recommended
  3. Defaults (.amplifier/skills, ~/.amplifier/skills, $AMPLIFIER_SKILLS_DIR) - fallback

Usage

How Skills Appear to Agents

When skills are configured, agents see them automatically before each request:

<available_skills>
Available skills (use load_skill tool):

- **python-testing**: Best practices for Python testing with pytest
- **git-workflow**: Git branching and commit message standards
- **api-design**: RESTful API design patterns and conventions
</available_skills>

The load_skill Tool

Operations:

  1. List skills: load_skill(list=true) - Show all available skills
  2. Search skills: load_skill(search="pattern") - Filter by keyword
  3. Get metadata: load_skill(info="skill-name") - Metadata only
  4. Load content: load_skill(skill_name="skill-name") - Full content

Usage in Bundles

---
bundle:
  name: module-creator
  description: Creates new Amplifier modules

includes:
  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
  - bundle: git+https://github.com/microsoft/amplifier-module-tool-skills@main#subdirectory=behaviors/skills.yaml
---

You are an Amplifier module creator.

Before creating modules:
1. Skills are visible automatically - review the available_skills list
2. Load relevant skills: load_skill(skill_name="module-development")
3. Follow the guidance from the skill

Agent Workflow Example

User: "Create a new tool module for database access"

Agent sees: <available_skills> containing "module-development"

Agent calls: load_skill(skill_name="module-development")
Response: [Full guide with protocols, entry points, patterns]

Agent: Creates module following the skill's patterns

Python API

from amplifier_module_tool_skills import SkillsTool

# Create tool
tool = SkillsTool(config={}, coordinator=None)

# List all skills
result = await tool.execute({"list": True})
# Returns: {"message": "...", "skills": [{"name": "...", "description": "..."}]}

# Search for skills
result = await tool.execute({"search": "python"})
# Returns: {"message": "...", "matches": [{"name": "python-standards", ...}]}

# Get metadata
result = await tool.execute({"info": "python-standards"})
# Returns: {"name": "...", "description": "...", "version": "...", ...}

# Load skill content
result = await tool.execute({"skill_name": "python-standards"})
# Returns: {"content": "# python-standards\n\n...", "skill_directory": "/path/to/skill"}

Creating Skills

Skills Directory Structure

Skills follow the Anthropic Skills format:

skills-directory/
├── design-patterns/
│   ├── SKILL.md          # Required: name and description in YAML frontmatter
│   └── examples/
│       └── module-pattern.md
├── python-standards/
│   ├── SKILL.md
│   ├── async-patterns.md
│   └── type-hints.md
└── module-development/
    └── SKILL.md

SKILL.md Format

Skills use YAML frontmatter with markdown body:

---
name: skill-name  # Required: unique identifier (lowercase with hyphens)
description: What this skill does and when to use it  # Required
version: 1.0.0
license: MIT
metadata:  # Optional
  category: development
  complexity: medium
---

# Skill Name

Instructions the agent follows when skill is loaded.

## Quick Start

[Minimal example to get started]

## Detailed Instructions

[Step-by-step guidance]

## Examples

[Concrete examples]

Required fields: name and description in YAML frontmatter
Format: See Anthropic Skills specification

Creating a Simple Skill

mkdir -p .amplifier/skills/my-skill
cat > .amplifier/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does something useful. Use when you need X.
version: 1.0.0
license: MIT
---

# My Skill

## Purpose

[What this skill does]

## Usage

[How to use it]

## Examples

[Complete examples]
EOF

Creating a Skill with References

mkdir -p .amplifier/skills/advanced-skill
cd .amplifier/skills/advanced-skill

# Main skill file
cat > SKILL.md << 'EOF'
---
name: advanced-skill
description: Advanced patterns
---

# Advanced Skill

## Quick Start

[Brief example]

## Detailed Guides

- See patterns.md for design patterns
- See examples.md for complete examples
EOF

# Reference files (loaded on-demand by agent using read_file)
echo "# Patterns Guide" > patterns.md
echo "# Examples" > examples.md

Module Contract

Module Type: Tool
Mount Point: tools
Entry Point: amplifier_module_tool_skills:mount

Testing

# Run all tests
uv run pytest

# Run specific test
uv run pytest tests/test_tool.py::test_list_skills -v

# Run with coverage
uv run pytest --cov

Local Development

For Module Developers

If you're developing the tool-skills module itself:

Option 1: Source Override (Recommended)

# Add to ~/.amplifier/settings.yaml
sources:
  tool-skills: file:///absolute/path/to/amplifier-module-tool-skills

Option 2: Workspace Convention

# In your development workspace
mkdir -p .amplifier/modules
ln -s /path/to/amplifier-module-tool-skills .amplifier/modules/tool-skills

Option 3: Environment Variable (Temporary)

export AMPLIFIER_MODULE_TOOL_SKILLS=/path/to/amplifier-module-tool-skills
amplifier run "test"

Testing Your Changes

# Install dependencies
uv sync

# Run tests
uv run pytest

# Format and check code
uv run ruff check .
uv run ruff format .

# Type checking
uv run pyright

Dependencies

  • amplifier-core - Core protocols and types
  • pyyaml>=6.0 - YAML parsing

Examples

See examples/skills-example.md for a complete working example showing:

  • How to include the skills behavior in your bundle
  • How to customize skills directories
  • Why direct behavior inclusion is recommended
  • Complete bundle structure

Contributing

Note

This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

Languages