Understanding Skills¶

Skills are one of Amplifier's most powerful features for extending agent capabilities. They provide a way to inject domain-specific knowledge, best practices, and workflows into your agents without modifying core system code.

What is a Skill?¶

A skill is loadable domain knowledge packaged as markdown files that agents can access on demand. Think of skills as specialized instruction manuals that agents can consult when they need expertise in a particular area.

Key Characteristics¶

• On-demand loading: Skills are loaded only when needed, keeping agent context lean
• Domain-specific: Each skill focuses on a particular area of expertise
• Declarative: Skills describe what to do, not how to implement it
• Composable: Multiple skills can be loaded together for complex tasks
• Versionable: Skills can be versioned and updated independently

Anatomy of a Skill¶

A skill typically consists of:

my-skill/
├── skill.md          # Main skill content (required)
├── examples/         # Optional companion files
│   ├── basic.py
│   └── advanced.py
└── templates/        # Optional templates
    └── config.yaml

The skill.md file contains:

1. Frontmatter: Metadata about the skill (name, version, description)
2. Context: Background knowledge the agent needs
3. Guidelines: Best practices and decision frameworks
4. Workflows: Step-by-step procedures for common tasks
5. Examples: Concrete illustrations of concepts

Automatic Visibility¶

Skills now appear in agent context automatically before each request. A visibility hook injects a summary of available skills so the agent always knows what expertise is accessible -- there is no need to call load_skill(list=True) first.

The max_skills_visible configuration option limits how many skills are shown in this automatic listing (default: 50). If you have more skills than the limit, the most relevant are shown based on discovery priority.

This automatic listing shows only Level 1 metadata (name and description). Loading the full skill content is still on-demand.

Progressive Disclosure Levels¶

Skills use a three-level progressive disclosure model to keep context lean:

Level 1 is always visible. Levels 2 and 3 are loaded on demand, so agents only consume context tokens when they actually need the deeper content.

Discovering Skills¶

The automatic visibility hook handles the common case, but you can also discover skills explicitly.

Listing All Skills¶

Use the load_skill tool with the list parameter:

load_skill(list=True)

This returns all available skills with their names and descriptions. With automatic visibility enabled, this is typically unnecessary but remains available for programmatic use.

Searching for Skills¶

If you're looking for skills in a specific domain:

load_skill(search="python")

This filters skills by name or description matching your search term.

Getting Skill Metadata¶

Before loading a full skill (which consumes context), you can inspect its metadata:

load_skill(info="design-patterns")

This returns the skill's name, description, version, and path without loading the full content.

Skill Discovery Locations¶

Skills are discovered from multiple directories in priority order:

1. Workspace skills (.amplifier/skills/) - Project-specific skills
2. User skills (~/.amplifier/skills/) - Personal skills across projects
3. Collection skills - Skills bundled with Amplifier collections

First-match-wins: if the same skill exists in multiple locations, the first one found is used.

Loading Skills¶

When you need domain expertise, load the relevant skill into context.

Basic Loading¶

load_skill(skill_name="python-standards")

This loads the full skill content and returns: - The skill content itself - The skill_directory path for accessing companion files

Accessing Companion Files¶

Many skills include additional resources like examples, templates, or reference files. Use the returned skill_directory to access them:

# Load the skill
result = load_skill(skill_name="api-design")
skill_dir = result["skill_directory"]

# Read a companion file
read_file(f"{skill_dir}/examples/rest-api.py")

When to Load Skills¶

Load skills when you need:

• Domain expertise: Working in an unfamiliar area
• Best practices: Ensuring code follows established patterns
• Consistency: Applying the same standards across a project
• Complex workflows: Following multi-step procedures correctly

Context Management¶

Skills consume context tokens when loaded. Best practices:

• Load skills on-demand, not preemptively
• Use info to check skill size before loading
• Load only the skills you actually need
• Consider skill size when working with limited context

Creating Skills¶

You can create custom skills for your projects or personal use.

Skill Structure¶

Create a directory with at least a skill.md file:

---
name: my-custom-skill
description: Brief description of what this skill provides
version: 1.0.0
---

# My Custom Skill

## Overview
Explain the domain this skill covers.

## Guidelines
List best practices and decision frameworks.

## Workflows
Document step-by-step procedures.

## Examples
Provide concrete illustrations.

Where to Place Skills¶

Choose based on scope:

Writing Effective Skills¶

Be specific: Focus on one domain or problem area.

# Good: Focused skill
---
name: react-testing
description: Testing patterns for React components
---

# Bad: Too broad
---
name: frontend
description: Everything about frontend development
---

Be actionable: Provide clear guidance, not just information.

# Good: Actionable guideline
When testing async components, always:
1. Use `waitFor` for state changes
2. Mock API calls at the network level
3. Test loading and error states

# Bad: Vague advice
Make sure to test your components properly.

Include examples: Show, don't just tell.

## Example: Testing a Form Component

```tsx
test('submits form data', async () => {
  render(<ContactForm />);

  await userEvent.type(screen.getByLabelText('Email'), 'test@example.com');
  await userEvent.click(screen.getByRole('button', { name: 'Submit' }));

  await waitFor(() => {
    expect(mockSubmit).toHaveBeenCalledWith({ email: 'test@example.com' });
  });
});

### Companion Files

For complex skills, include additional resources:

my-skill/ ├── skill.md ├── examples/ │ ├── basic-usage.py │ └── advanced-patterns.py ├── templates/ │ └── project-structure/ └── reference/ └── cheatsheet.md

Reference these in your skill content:

```markdown
## Getting Started

See `examples/basic-usage.py` for a minimal working example.

For production patterns, refer to `examples/advanced-patterns.py`.

Bundle-Level Skill Configuration¶

When distributing skills as part of a bundle, configure them in the tools: section under the tool-skills module:

tools:
  - module: tool-skills
    config:
      skills:
        - "git+https://github.com/org/repo@main#subdirectory=skills"
        - "@mybundle:skills"

This tells the skill system where to discover skills when the bundle is loaded.

WARNING: Do NOT use a top-level skills: key in bundle frontmatter. It is silently ignored. Skills must be configured under tools: config as shown above. This is a common mistake that produces no error -- the skills simply never appear.

Supported Skill Sources in Bundle Config¶

Registering New Skill Sources at Runtime¶

You can register additional skill sources dynamically using the load_skill tool:

# Register a git-hosted skill collection
load_skill(source="git+https://github.com/org/shared-skills@main")

# Register skills from another bundle
load_skill(source="@mybundle:skills")

Once registered, the new skills appear in the automatic visibility listing and can be loaded like any other skill. This is useful when you need to pull in skills from external repositories or other bundles mid-session.

Key Takeaways¶

1. Skills are loadable expertise: They inject domain knowledge into agents on demand, keeping base context lean while enabling deep specialization.

2. Automatic visibility: Skills are listed automatically before each request via a visibility hook. Agents always know what skills are available without explicit discovery calls.

3. Progressive disclosure preserves context: Level 1 metadata (~100 tokens) is always visible. Full content (Level 2) and companion files (Level 3) load on demand.

4. Location determines scope: Workspace skills override user skills, enabling project-specific customization while maintaining personal defaults.

5. Configure skills in bundles under tools:: Use the tool-skills module config, not top-level skills: frontmatter (which is silently ignored).

6. Register sources at runtime: Use load_skill(source="...") to add git repositories or bundle paths as skill sources mid-session.

7. Focus on actionability: The best skills provide clear guidelines, decision frameworks, and concrete examples -- not just reference information.

8. Companion files extend capabilities: Skills can include examples, templates, and reference materials that agents access via the skill_directory path.

9. Context is precious: Load skills judiciously. Each loaded skill consumes tokens that could be used for other context.

Related Concepts¶

• Agents - How agents use skills
• Bundles - Packaging skills with other components
• Architecture - System design and structure