Mastering Agent Skill Patterns

Explore the common structural patterns for building effective agent skills, from instruction-only guides to complex hybrid systems.

Posted on: 2026-03-04 by AI Assistant

In the world of AI agents, “Skills” are the building blocks that extend capabilities beyond basic reasoning. Whether you’re providing a set of best practices or integrating complex external APIs, choosing the right structural pattern for your skill is crucial for maintainability and performance.

This guide explores five common patterns used to build robust agent skills.

Pattern 1: Instruction-Only Skills

Best for: Methodology, best practices, and workflow templates.

Instruction-only skills are the simplest form. They provide the agent with a “mental model” or a specific process to follow without requiring external scripts.

Example: Web Research Skill

---
name: web-research
description: Structured approach to conducting comprehensive web research
---

# Web Research Skill

## Process

### Step 1: Create Research Plan
Before conducting research:
1. Analyze the research question
2. Break it into 2-5 distinct subtopics
3. Determine expected information from each

### Step 2: Gather Information
For each subtopic:
1. Use web search tools with clear queries
2. Target 3-5 searches per subtopic
3. Organize findings as you gather them

Example Use Cases:

• Web research methodologies
• Code review checklists
• Writing style guides

Pattern 2: Script-Based Skills

Best for: API integrations, data processing, and interacting with external services.

When an agent needs to do something—like fetch papers from arXiv or check a stock price—script-based skills are the answer. They utilize custom code (often Python or Shell) to bridge the gap between the LLM and the real world.

Example: arXiv Search Skill

#!/usr/bin/env python3
import sys
import argparse

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('query', help='Search query')
    parser.add_argument('--max-papers', type=int, default=10)

    args = parser.parse_args()

    # Perform search logic here
    results = search_arxiv(args.query, args.max_papers)

    for paper in results:
        print(f"Title: {paper['title']}")
        print(f"URL: {paper['url']}")

if __name__ == "__main__":
    main()

Example Use Cases:

• Searching academic databases
• Interacting with local file systems
• Triggering CI/CD pipelines

Pattern 3: Documentation Reference Skills

Best for: Quick reference guides and documentation shortcuts.

These skills act as a curated index for external knowledge. Instead of embedding entire manuals, they provide high-level summaries and direct links to official documentation.

Example: Framework Documentation Skill

---
name: pydanticai-docs
description: Access Pydantic AI framework documentation
---

# Pydantic AI Documentation Skill

## Instructions

### For General Documentation
The complete Pydantic AI documentation is available at:
https://ai.pydantic.dev/

### Key Concepts
- **Agents**: Create with `Agent(model, instructions, tools)`
- **Tools**: Decorate with `@agent.tool`
- **Output**: Use `result_type` parameter for structured output

Example Use Cases:

• Framework documentation shortcuts (e.g., Pydantic AI)
• Internal company policy references
• Standard library cheat sheets

Pattern 4: Multi-Resource Skills

Best for: Complex APIs and template collections.

For more sophisticated integrations, a single Markdown file isn’t enough. Multi-resource skills organize documentation into logical sections (API references, schemas, examples) to help the agent navigate complex information efficiently.

Example Structure

api-integration/
├── SKILL.md
├── API_REFERENCE.md
└── resources/
    ├── examples.json
    └── schemas/
        ├── request.json
        └── response.json

Example Use Cases:

• Large-scale enterprise API integrations
• Document template libraries
• Configuration schema repositories

Pattern 5: Hybrid Skills

Best for: Complex, multi-step workflows.

The most powerful skills combine instructions, scripts, and multiple resources. They guide the agent through a complete lifecycle—from reviewing reference data to executing analysis scripts and generating visualizations.

Example Workflow

# Step 1: Review Sample Format
read_skill_resource(skill_name="data-analyzer", resource_name="resources/sample_data.csv")

# Step 2: Run Analysis
run_skill_script(skill_name="data-analyzer", script_name="analyze", args=["data.csv"])

# Step 3: Generate Visualization
run_skill_script(skill_name="data-analyzer", script_name="visualize", args=["data.csv", "--type", "histogram"])

Example Use Cases:

• End-to-end data analysis pipelines
• Automated security auditing
• Complex code migration tools

Choosing the Right Pattern

When deciding which pattern to use, ask yourself:

1. Does it need code? If yes, use Pattern 2 or 5.
2. Is it purely informational? Use Pattern 1 or 3.
3. Is the information large or structured? Use Pattern 4.

By matching the structure of your skill to its function, you ensure your AI agents operate with maximum clarity and efficiency.