#Writing Effective Skill Files

A skill file is only as good as the knowledge it transfers. Here's how to write skills that agents can actually use effectively.

#The Anatomy of a Great Skill

#Frontmatter

Every skill starts with YAML frontmatter:

---
name: api-design-patterns description: >   Design RESTful APIs with proper resource modeling,   versioning, error handling, and pagination patterns. ---

The description field is critical — it's what agents use to decide whether to load the skill. Make it specific enough to match the right tasks, but broad enough to be discoverable.

#Role Introduction

Start with a clear role statement:

# API Design Specialist
You are a senior API architect who specializes in designing clean, consistent, and scalable REST APIs.

This sets the agent's persona and expertise level.

#Philosophy Section

Explain the why before the how:

## Core Philosophy
APIs are contracts. Every endpoint is a promise to your consumers. Breaking changes break trust. Design for the consumer, not for your database schema.

This gives the agent a decision-making framework.

#Techniques (the core content)

This is where the expertise lives. Be specific and actionable:

## Key Techniques
#Resource Modeling
Design resources around domain nouns, not verbs:

/users/{id}/orders not /getUserOrders
Use plural nouns: /users not /user
Nest resources max 2 levels deep

#Best Practices

Concrete, numbered rules that the agent can follow:

## Best Practices

Use HTTP status codes correctly (201 for created, 204 for no content)
Include pagination for all list endpoints
Version your API in the URL path (/v1/users)
Return consistent error response format

#Anti-Patterns

What NOT to do is just as important:

## Anti-Patterns

Exposing internal database IDs without UUIDs
Returning different error formats from different endpoints
Using POST for everything
Putting business logic in URL query parameters

#Common Mistakes in Skill Writing

#Too Vague

Bad: "Write clean code." Good: "Functions should do one thing. If the function name needs 'and' in it, split it."

#Too Specific to One Stack

Bad: "Use Express.js middleware for authentication." Good: "Implement authentication as middleware/interceptor that runs before route handlers."

#Missing the Why

Bad: "Always use UUIDs for IDs." Good: "Use UUIDs for public-facing IDs to prevent enumeration attacks and hide creation order."

#No Anti-Patterns

Anti-patterns are often more valuable than best practices. Agents learn faster from "don't do X because Y happens" than from "do X."

#The Three Skill Types

#Functional Skills

How-to knowledge with philosophy, techniques, and practices. Best for: teaching agents to perform specific tasks.

#Person Styles

Working in the style of a specific practitioner. Best for: creative work, writing, design.

#Critic Styles

Evaluating work through a specific critical lens. Best for: review, feedback, quality assessment.

#Testing Your Skill

Before publishing, test it:

1. Give an agent a task in the skill's domain WITHOUT the skill
2. Give the same task WITH the skill loaded
3. Compare the output quality

If the skill-loaded version isn't noticeably better, the skill needs more depth.