How to Build Agent Skills: A Step-by-Step Tutorial

As part of our comprehensive guide to agent skills, this tutorial provides practical, hands-on guidance for creating your first production-ready agent skill. If you’re still unclear on what distinguishes skills from other AI capabilities, review Agent Skills vs Function Calling before proceeding.

Building effective agent skills requires understanding both the technical structure and the design principles that make skills useful. This tutorial walks you through the entire process.

Table of Contents

Prerequisites

Before building your first skill, ensure you have:

  • Access to an AI agent platform that supports skills (Google Antigravity, Spring AI, or similar)
  • Basic understanding of markdown or YAML formatting
  • A clear use case or problem to solve
  • Access to domain expertise (either your own or from subject matter experts)

No programming experience is strictly required. Skills are primarily composed of structured text, not code.

Understanding Skill Structure

Most agent skill systems follow a similar organizational pattern. A typical skill consists of:

Core Files:

  • `SKILL.md` – The main instruction file

  • `README.md` – Optional documentation for developers

Supporting Resources:

  • `/examples/` – Sample interactions and outputs

  • `/templates/` – Reusable response formats

  • `/scripts/` – Helper utilities (if supported)

The skill file itself typically contains:

  • Frontmatter metadata (YAML)

  • Markdown-formatted instructions

  • Examples and edge cases

[IMAGE PROMPT: Folder structure diagram showing SKILL.md at top level with examples, templates, and scripts subdirectories]

Step 1: Define Your Skill Scope

The most critical decision is scoping your skill correctly. Skills that try to do too much become unwieldy. Skills too narrow become trivial.

Ask These Questions

What specific problem does this skill solve?

Be concrete. “Help with customer support” is too broad. “Guide refund request processing for software subscriptions” is appropriately focused.

Who is the target user?

Understanding your audience shapes instruction style. Internal analysts need different guidance than external customers.

What are the inputs and outputs?

Define what information the skill expects and what it produces. This creates clear expectations for both the agent and users.

What are the skill boundaries?

Explicitly state what this skill does NOT handle. This prevents scope creep and clarifies handoff points.

Document Your Scope

Create a scope document before writing any skill content:

Skill Name: Subscription Refund Processor
Problem: Guide agents through subscription refund decisions
Target User: Customer support agents
Inputs: Customer request, order history, account status
Outputs: Refund decision, customer communication
Out of Scope: Hardware refunds, enterprise contracts, fraud cases

This document becomes your north star during development.

Step 2: Gather Domain Knowledge

Effective skills embed real expertise. Collecting that expertise requires systematic effort.

Interview Subject Matter Experts

Schedule conversations with people who currently do the task your skill will support. Ask:

  • What steps do you follow for this task?
  • What information do you need to make decisions?
  • What mistakes do beginners commonly make?
  • What edge cases require special handling?
  • How do you know when you’ve done a good job?

Record these conversations (with permission) for reference during skill writing.

Review Existing Documentation

Collect all relevant written materials:

  • Process documents and SOPs
  • Training materials
  • FAQ documents
  • Past decision records
  • Exception handling guidelines

These materials provide structure and detail that interviews might miss.

Analyze Successful Interactions

If possible, review examples of the task being performed well:

  • Support ticket histories
  • Chat logs
  • Decision records
  • Customer feedback

Identify patterns that indicate quality execution.

Organize Your Knowledge

Structure your collected knowledge into categories:

  • Core procedures – The main workflow steps
  • Decision criteria – How to make key judgments
  • Quality standards – What good output looks like
  • Common pitfalls – Mistakes to avoid
  • Edge cases – Unusual situations requiring special handling

[IMAGE PROMPT: Mind map showing knowledge organization with core procedures at center, branching to criteria, standards, pitfalls, and edge cases]

Step 3: Create the Skill File Structure

With your scope defined and knowledge collected, create the skill’s file structure.

Directory Setup

Create your skill directory:

my-skill/
├── SKILL.md
├── README.md (optional)
└── examples/
    └── sample-interactions.md

For complex skills, add more subdirectories as needed. Keep the structure as simple as your skill allows.

Naming Conventions

Use clear, descriptive names:

  • Skill directories: `kebab-case` (e.g., `subscription-refund-processor`)
  • Files: `SCREAMING_SNAKE` for core files, `kebab-case` for content
  • Examples: Descriptive names indicating the scenario

Step 4: Write the Skill Definition

The skill definition file (typically SKILL.md) contains metadata and instructions.

Frontmatter Structure

Begin with YAML frontmatter that declares skill metadata:

---
name: subscription-refund-processor
description: Guide agents through subscription refund decisions for software products. Use this skill when customers request refunds for digital subscription purchases.
version: 1.0.0
author: Customer Success Team
---

Key frontmatter fields:

  • name – Unique identifier for the skill
  • description – Clear explanation of when to use this skill
  • version – Semantic version for tracking changes
  • author – Team or individual responsible

Trigger Conditions

Describe when this skill should activate:

## When to Use This Skill

Activate this skill when:
- A customer requests a refund for a subscription product
- The subscription is for software, not physical goods
- The request is from an individual customer, not an enterprise account

Do NOT use this skill when:
- The refund involves physical merchandise
- The customer is on an enterprise contract
- Fraud is suspected

Clear trigger conditions prevent inappropriate skill activation.

Step 5: Craft Effective Instructions

The instruction section is your skill’s core. Write instructions that guide reasoning, not just list facts.

Instruction Writing Principles

Be specific and concrete. Vague guidance produces inconsistent results. Instead of “be helpful,” specify what helpful behavior looks like.

Use imperative voice. Direct instructions are clearer than passive descriptions. “Check the order date” not “The order date should be checked.”

Progress from general to specific. Start with the overall approach, then provide detailed guidance for each step.

Include decision criteria. Whenever the agent must make a judgment, provide explicit criteria.

Structure Your Instructions

Organize instructions into clear sections:

## Overall Approach

When processing a refund request, follow these steps in order:
1. Verify customer identity and order
2. Assess refund eligibility
3. Calculate refund amount
4. Process or escalate as appropriate
5. Communicate decision to customer

## Step 1: Verify Customer Identity

Before proceeding, confirm:
- The customer owns the account in question
- The order ID matches their account history
- The subscription is the one they're asking about

## Step 2: Assess Refund Eligibility

Refunds are approved when:
- Request is within 30 days of purchase
- Customer has not used more than 50% of the subscription period
- No previous refund was issued for this subscription

Refunds require escalation when:
- Request is between 30-60 days after purchase
- Customer claims service failure
- Amount exceeds $500

Refunds are denied when:
- Request is more than 60 days after purchase
- Full subscription period has been consumed
- Evidence of policy abuse exists

Include Examples Within Instructions

Show, don’t just tell. Include mini-examples throughout:

## Calculating Partial Refunds

When a partial refund is appropriate, calculate:

Refund = (Remaining Days / Total Days) × Original Price

**Example:** Customer paid $120 for a 12-month subscription. After 4 months, they request a refund.
- Remaining: 8 months
- Calculation: (8/12) × $120 = $80 refund

Step 6: Add Examples and Templates

Supplement your instructions with detailed examples and response templates.

Example Interactions

Create realistic scenarios showing the skill in action:

# Example: Standard Refund Approval

**Customer Request:** "I purchased your Pro plan last week but it doesn't have the features I expected. Can I get a refund?"

**Agent Response:** "I've reviewed your account and can certainly help with that. Your Pro plan was purchased 4 days ago, which is well within our 30-day refund window. Since you haven't used any of the premium features yet, I'll process a full refund of $29.99 to your original payment method. You should see this within 5-7 business days. Is there anything else I can help you with today?"

**Why This Works:**
- Verified timeline (within 30 days)
- Checked usage (minimal)
- Provided clear amount and timeline
- Offered further assistance

Response Templates

Provide templates for common scenarios:

## Refund Approval Template

[Customer Name], I've reviewed your request and I'm happy to confirm we can process a [full/partial] refund.

**Refund Details:**
- Amount: [$$]
- Original purchase: [Date]
- Processing time: 5-7 business days
- Return to: [Original payment method]

[Additional context if partial refund or special circumstances]

Is there anything else I can help you with?

Step 7: Test Your Skill

Before deployment, rigorous testing ensures your skill performs reliably.

Create Test Cases

Develop test scenarios covering:

  • Happy path – Standard, expected usage
  • Edge cases – Boundary conditions and unusual situations
  • Failure modes – Requests that should be rejected or escalated
  • Ambiguous inputs – Situations requiring judgment

For each test case, document:

  • Input scenario

  • Expected behavior

  • Actual result

  • Pass/fail assessment

Testing Methodology

Run your test cases with the agent:

  1. Load the skill into your agent environment
  2. Present each test scenario
  3. Evaluate the response against expectations
  4. Note any deviations or unexpected behavior

Track results systematically. Testing isn’t complete until all critical paths pass consistently.

Iterative Refinement

Testing reveals instruction gaps. Common discoveries:

  • Missing decision criteria for edge cases
  • Ambiguous wording causing inconsistent interpretation
  • Insufficient examples for complex scenarios
  • Overly rigid instructions that break in valid situations

Return to Step 5 to refine instructions based on test findings.

Step 8: Iterate and Refine

Skills improve through iteration. Plan for multiple revision cycles.

Feedback Collection

After initial deployment:

  • Monitor skill usage logs
  • Collect user feedback
  • Review escalated cases
  • Track success metrics

Common Refinements

Most skills require adjustments in:

  • Scope clarification – Adding explicit out-of-scope statements
  • Edge case handling – Addressing situations not anticipated
  • Instruction clarity – Rephrasing confusing guidance
  • Example expansion – Adding scenarios for common questions

Version Management

Track changes through versioning:

---
version: 1.1.0
changelog:
  - 1.1.0: Added enterprise contract escalation path
  - 1.0.1: Clarified partial refund calculation
  - 1.0.0: Initial release
---

For architectural considerations when managing multiple skills, see Agent Skills Architecture.

Step 9: Document and Deploy

Proper documentation ensures your skill remains useful over time.

Documentation Elements

Create documentation covering:

  • Purpose – What the skill does and why
  • Usage – When and how to activate the skill
  • Configuration – Any customization options
  • Maintenance – How to update the skill
  • Ownership – Who is responsible for the skill

Deployment Checklist

Before final deployment:

  • [ ] All test cases pass
  • [ ] Documentation is complete
  • [ ] Stakeholders have reviewed and approved
  • [ ] Rollback plan is in place
  • [ ] Monitoring is configured
  • [ ] Support team is briefed

Common Mistakes to Avoid

Learn from others’ errors to accelerate your skill development.

Mistake: Instructions Too Vague

Problem: “Handle refunds appropriately based on policy” leaves too much interpretation.

Solution: Specify exactly what “appropriately” means with concrete criteria.

Mistake: No Edge Case Coverage

Problem: Skills work for standard cases but fail on exceptions.

Solution: Explicitly identify and document edge cases during knowledge gathering.

Mistake: Ignoring Context Limits

Problem: Skills so detailed they consume the entire context window.

Solution: Be concise. Use examples sparingly. Link to external resources for deep details.

Mistake: No Failure Path

Problem: Skills assume success and don’t guide error handling.

Solution: Include explicit guidance for when things go wrong.

Mistake: Testing Only Happy Paths

Problem: Skills seem to work but fail in production on unusual inputs.

Solution: Design test cases specifically for failure modes and edge cases.

For security-focused guidance, continue to Agent Skills Security.

Conclusion

Building effective agent skills is a craft that improves with practice. The key steps are:

  1. Define scope carefully – Know exactly what your skill should do
  2. Gather real expertise – Ground your skill in actual domain knowledge
  3. Structure clearly – Organize instructions for easy comprehension
  4. Test rigorously – Verify behavior across all scenarios
  5. Iterate continuously – Improve based on real-world feedback

Start with a simple skill addressing a well-understood problem. Master the fundamentals before tackling complex, multi-faceted skills.

The investment in building quality skills pays dividends in agent reliability and capability. Every skill you create makes your AI systems more valuable.

Begin your skill-building journey today. Your first skill doesn’t need to be perfect—it needs to be started.

Related Posts

Leave a Reply