Agents & Skills

As AI systems evolve from simple question-answering to autonomous task execution, understanding agents and skills becomes essential. This chapter explores how prompts serve as the fundamental building blocks for AI agents, and how skills package expertise into reusable, comprehensive instruction sets.

What Are AI Agents?

An AI agent is an AI system that can autonomously plan, execute, and iterate on tasks. Unlike simple prompt-response interactions, agents can:

• Plan - Break down complex goals into actionable steps
• Execute - Use tools and take actions in the real world
• Observe - Process feedback from their actions
• Adapt - Adjust their approach based on results
• Persist - Maintain context and memory across interactions

Prompts as Building Blocks

Every agent, no matter how sophisticated, is built from prompts. Just as atoms combine to form molecules, and molecules combine to form complex structures, prompts combine to create intelligent agent behavior.

These prompt types stack together to form complete agent behavior:

System Prompts (The Agent's Identity)

The foundational prompt that establishes who the agent is and how it behaves:

You are a code review assistant. Your role is to:
- Analyze code for bugs, security issues, and performance problems
- Suggest improvements following best practices
- Explain your reasoning clearly
- Be constructive and educational in feedback

You have access to tools for reading files, searching code, and running tests.

Planning Prompts (How to Think)

Instructions that guide the agent's reasoning and planning process:

Before taking action, always:
1. Understand the complete request
2. Break it into smaller, verifiable steps
3. Identify which tools you'll need
4. Consider edge cases and potential issues
5. Execute step by step, validating as you go

Tool-Use Prompts (How to Act)

Guidance on when and how to use available tools:

When you need to understand a codebase:
- Use grep_search for finding specific patterns
- Use read_file to examine file contents
- Use list_dir to explore directory structure
- Always verify your understanding before making changes

Recovery Prompts (How to Handle Failure)

Instructions for when things go wrong:

If an action fails:
1. Analyze the error message carefully
2. Consider alternative approaches
3. Ask for clarification if the task is ambiguous
4. Never repeat the same failed action without changes

What Are Skills?

If prompts are the atoms, skills are the molecules—reusable building blocks that give agents specific capabilities.

A skill is a comprehensive, portable package of instructions that gives an AI agent expertise in a specific domain or task. Skills are the reusable blocks of agents: you build them once, and any agent can use them.

Anatomy of a Skill

A well-designed skill typically includes:

Example: Code Review Skill

Here's what a code review skill might look like:

The SKILL.md file defines the overall approach:

---
name: code-review
description: Comprehensive code review with security, performance, and style analysis
---

# Code Review Skill

You are an expert code reviewer. When reviewing code:

## Process
1. **Understand Context** - What does this code do? What problem does it solve?
2. **Check Correctness** - Does it work? Are there logic errors?
3. **Security Scan** - Reference security-checklist.md for common vulnerabilities
4. **Performance Review** - Check performance-tips.md for optimization opportunities
5. **Style & Maintainability** - Is the code readable and maintainable?

## Output Format
Provide feedback in categories:
- 🔴 **Critical** - Must fix before merge
- 🟡 **Suggested** - Recommended improvements
- 🟢 **Nice to have** - Optional enhancements

Always explain *why* something is an issue, not just *what* is wrong.

Skills vs. Simple Prompts

Building Effective Skills

1. Define the Expertise Clearly

Start with a clear description of what the skill enables:

---
name: api-design
description: Design RESTful APIs following industry best practices, 
  including versioning, error handling, and documentation standards
---

2. Structure Knowledge Hierarchically

Organize information from general to specific:

# API Design Skill

## Core Principles
- Resources should be nouns, not verbs
- Use HTTP methods semantically
- Version your APIs from day one

## Detailed Guidelines
[More specific rules...]

## Reference Materials
- See `rest-conventions.md` for naming conventions
- See `error-codes.md` for standard error responses

3. Include Concrete Examples

Abstract rules become clear with examples:

## Endpoint Naming

✅ Good:
- GET /users/{id}
- POST /orders
- DELETE /products/{id}/reviews/{reviewId}

❌ Avoid:
- GET /getUser
- POST /createNewOrder
- DELETE /removeProductReview

4. Provide Decision Frameworks

Help the agent make choices in ambiguous situations:

## When to Use Pagination

Use pagination when:
- Collection could exceed 100 items
- Response size impacts performance
- Client may not need all items

Use full response when:
- Collection is always small (<20 items)
- Client typically needs everything
- Real-time consistency is critical

5. Add Recovery Patterns

Anticipate what can go wrong:

## Common Issues

**Problem**: Client needs fields not in standard response
**Solution**: Implement field selection: GET /users?fields=id,name,email

**Problem**: Breaking changes needed
**Solution**: Create new version, deprecate old with timeline

Composing Skills

Agents become powerful when multiple skills work together. Consider how skills can complement each other:

When composing skills, ensure they don't conflict. Skills should be:

• Modular - Each skill handles one domain well
• Compatible - Skills shouldn't give contradictory instructions
• Prioritized - When skills overlap, define which takes precedence

Sharing and Discovering Skills

Skills are most valuable when shared. Platforms like prompts.chat allow you to:

• Discover community-created skills for common tasks
• Download skills directly to your projects
• Share your own expertise as reusable skills
• Iterate on skills based on real-world usage

The Agent-Skill Ecosystem

The relationship between agents and skills creates a powerful ecosystem:

The agent provides the execution framework—planning, tool use, and memory—while skills provide domain expertise. This separation means:

• Skills are portable - The same skill works with different agents
• Agents are extensible - Add new capabilities by adding skills
• Expertise is shareable - Domain experts can contribute skills without building full agents

Best Practices

For Building Skills

1. Start specific, then generalize - Build a skill for your exact use case first, then abstract
2. Include failure cases - Document what the skill can't do and how to handle it
3. Version your skills - Track changes so agents can depend on stable versions
4. Test with real tasks - Validate skills against actual work, not just theory

For Using Skills with Agents

1. Read the skill first - Understand what a skill does before deploying it
2. Customize thoughtfully - Override skill defaults only when necessary
3. Monitor performance - Track how well skills perform in your context
4. Contribute improvements - When you improve a skill, consider sharing back