Create Agent Skills

A guide for creating new Agent Skills following the AgentSkills.io specification. Agent Skills are portable, structured knowledge units that give AI coding assistants specialized capabilities.

When to Use

• Creating a brand-new skill from scratch
• Adding domain-specific knowledge for an AI agent
• Structuring reusable patterns, workflows, or best practices as a skill
• Defining how the agent should handle a specific technology or task

---

Quick Start: Minimal Skill

SKILL_NAME="my-skill-name"
mkdir -p "data_product_accelerator/skills/admin/${SKILL_NAME}"

Then create SKILL.md:

---
name: my-skill-name
description: What this skill does. When to use it. Trigger phrases and scenarios.
---

# My Skill Title

Brief overview.

## When to Use

- Scenario 1
- Scenario 2

## Instructions

Step-by-step guidance.

## Examples

Concrete examples.

---

Required Fields

name (Required)

Rule	Detail
Max length	64 characters
Characters	a-z, 0-9, - only
No leading/trailing hyphens	my-skill OK, -my-skill- BAD
No consecutive hyphens	my-skill OK, my--skill BAD
Must match directory name	my-skill/SKILL.md → name: my-skill

description (Required)

Rule	Detail
Max length	1024 characters
Must be non-empty	Cannot be blank
Third person voice	"Provides guidance..." not "I provide..."
Include WHAT + WHEN	Describe what the skill does AND when to use it
Include trigger phrases	Keywords that should activate this skill

Good example:

description: Provides patterns for creating Databricks Delta Live Tables (DLT) pipelines with data quality expectations. Covers streaming ingestion, quarantine patterns, and expectation configuration. Use when building Silver layer pipelines, adding data quality checks, or configuring DLT expectations. Triggers on "DLT", "expectations", "streaming", "quarantine".

---

Optional Fields

license: Apache-2.0                    # SPDX license identifier
metadata:
  author: your-name                    # Author or team
  version: "1.0.0"                     # Semantic version (quoted)
  domain: admin                        # Domain category
  source: "Description of origin"      # Where the knowledge came from

---

Directory Structure

my-skill/
├── SKILL.md              # REQUIRED — Main instructions (<500 lines)
├── references/           # OPTIONAL — Detailed docs loaded on demand
│   ├── api-reference.md
│   └── advanced-patterns.md
├── scripts/              # OPTIONAL — Executable utilities
│   └── validate.py
└── assets/
    └── templates/        # OPTIONAL — Starter files to copy
        └── config.yaml

When to Create Each Directory

Directory	Create When...
references/	SKILL.md would exceed 500 lines without splitting
scripts/	Reusable code blocks exceed 10 lines
assets/templates/	Templates, configs, or starter files exist

---

Progressive Disclosure

Core principle: Keep SKILL.md lightweight. Move details to subdirectories.

What Stays in SKILL.md (~1-2K tokens)

• Overview and purpose
• Critical rules (the "never do X" type)
• Quick reference tables
• Links to references, scripts, assets
• Decision guides

What Moves to references/

• Comprehensive API docs
• Extended pattern libraries
• Validation checklists
• Troubleshooting guides
• Edge case documentation

What Moves to scripts/

• Validation utilities
• Setup automation
• Code generation tools
• Data extraction helpers

What Moves to assets/templates/

• YAML configuration templates
• SQL DDL templates
• Job configuration starters
• Skeleton files to copy

Working Memory (Orchestrators Only)

Orchestrator skills with 3+ phases must include a ## Working Memory Management section. Workers must end with a ## [Domain] Notes to Carry Forward section and a ## Next Step section. See Progressive Disclosure Patterns for Strategy 4 details.

---

Naming and Organization

Skill Location

Place skills under data_product_accelerator/skills/{domain}/:

skills/
├── admin/            # Administrative skills
├── bronze/           # Bronze layer patterns
├── silver/           # Silver layer patterns
├── gold/             # Gold layer patterns
├── common/           # Cross-cutting concerns
├── semantic-layer/   # Metric views, TVFs, Genie
├── monitoring/       # Monitoring, dashboards, alerts
├── ml/               # Machine learning patterns
├── planning/         # Project planning
└── exploration/      # Ad-hoc analysis

File Naming

• Directories: kebab-case (e.g., my-skill-name/)
• SKILL.md: Always SKILL.md (exact casing)
• References: kebab-case.md (e.g., api-reference.md)
• Scripts: snake_case.py or kebab-case.sh
• Templates: kebab-case.yaml, kebab-case.sql

---

Skill Quality Checklist

Before finalizing a new skill:

Structure

• name matches directory name, max 64 chars, valid characters
• description includes WHAT + WHEN + trigger phrases, max 1024 chars
• SKILL.md is under 500 lines
• References are one level deep (no nested references)

Content

• Instructions are actionable (agent can follow them)
• Examples are concrete, not abstract
• Correct and incorrect patterns shown where applicable
• Links to references/ files use relative paths

Discovery

• Description has clear trigger keywords
• Skill is registered in skill-navigator (update Tier 3 table + routing table + directory map)
• Domain index in navigator references/ is updated

---

After Creating a Skill

Always update the skill-navigator:

1. Add to Tier 3 table in skill-navigator/SKILL.md
2. Add routing keywords to the Task Detection & Routing Table
3. Add to the Complete Skill Directory Map
4. Update the appropriate domain index in skill-navigator/references/domain-indexes.md

---

Additional Resources

• AgentSkills.io Specification — Official format specification
• Progressive Disclosure Patterns — How to split large skills
• Skill Examples — Annotated examples of well-structured skills