Skills: Teaching the Agent Expertise

What Are Skills?

Skills are structured knowledge packages that give the agent deep expertise in specific domains. Think of them as “specialist training” — instead of generic knowledge, the agent gets detailed patterns, best practices, and decision frameworks.

Skills live in .agent/skills/ and contain:

• SKILL.md — The main instruction file (required)
• scripts/ — Helper scripts the agent can execute
• examples/ — Reference implementations
• resources/ — Templates, assets, and data files

How Skills Work

When the agent encounters a task that matches a skill, it:

1. Reads the SKILL.md file
2. Loads relevant sections (not everything)
3. Applies the skill’s principles to the current task
4. Uses scripts/examples if needed

Skill Loading Protocol

Task received → Check if skill applies
  → Read SKILL.md (index)
  → Read only relevant sections
  → Apply principles to generate response

Important: The agent reads selectively. A 500-line skill file doesn’t mean 500 lines of context used — only the relevant parts load.

Built-in vs Custom Skills

Common Built-in Skills

Skill	What It Does
clean-code	Enforces concise, self-documenting code
frontend-design	Design thinking for web UI/UX
tailwind-patterns	Tailwind CSS v4 best practices
testing-patterns	Unit, integration, mocking strategies
seo-fundamentals	SEO optimization rules
performance-profiling	Measurement and optimization techniques
vulnerability-scanner	OWASP 2025 security scanning
systematic-debugging	4-phase debugging methodology

Creating a Custom Skill

Create .agent/skills/my-api/SKILL.md:

---
name: my-api-patterns
description: API design patterns for our microserv stack
---

# API Design Skill

## Response Format

All APIs must return:
{
"data": T,
"meta": { "page": number, "total": number },
"error": null | { "code": string, "message": string }
}

## Authentication

- All endpoints require Bearer token
- Use middleware, never check auth in handlers
- Rate limit: 100 req/min for authenticated, 10 for anonymous

## Error Handling

- Always return appropriate HTTP status codes
- Log errors with request ID for tracing
- Never expose internal errors to clients

Now whenever the agent works on API endpoints, it follows YOUR patterns automatically.

Skills with Scripts

Skills can include executable scripts that extend the agent’s capabilities:

.agent/skills/testing-patterns/
├── SKILL.md
└── scripts/
    ├── test_runner.py    → Runs tests with coverage
    ├── lint_runner.py    → Lints code and reports issues
    └── coverage_check.py → Validates coverage thresholds

The agent can invoke these:

python .agent/skills/testing-patterns/scripts/test_runner.py

Real Example: UX Audit Script

# .agent/skills/frontend-design/scripts/ux_audit.py
"""
Checks for common UX issues:
- Missing aria labels
- Color contrast violations
- Touch target sizes
- Loading state indicators
"""

import sys
from pathlib import Path

def audit_component(filepath):
    content = Path(filepath).read_text()
    issues = []

    if 'onClick' in content and 'aria-label' not in content:
        issues.append("Missing aria-label on clickable element")

    if 'cursor-pointer' in content and 'focus:' not in content:
        issues.append("Missing focus styles on interactive element")

    return issues

Combining Multiple Skills

The agent can combine skills for complex tasks. For example, building a new feature might use:

Task: "Build a user profile page"

Skills activated:
├── frontend-design → Layout and UI patterns
├── clean-code → Code quality standards
├── tailwind-patterns → Styling approach
├── testing-patterns → Write component tests
└── seo-fundamentals → Meta tags and structure

Task Groups

Task Groups let you bundle related tasks that should be executed together:

• Group multiple files that need to change atomically
• Define dependencies between tasks
• Ensure prerequisites are met before starting

This is especially useful for refactoring across many files.

Best Practices

1. One skill, one domain — Don’t mix API patterns with UI rules
2. Keep SKILL.md focused — The agent reads selectively, but clarity helps
3. Include anti-patterns — Show what NOT to do
4. Add practical examples — Real code speaks louder than rules
5. Version your skills — They’re part of your project, commit them

What’s Next

We’ve covered how the agent thinks (modes), what it follows (rules), and what it knows (skills). Next, let’s explore the powerful tools it can use — MCP, Browser, and Artifacts.