Agent Skills Explained: From Specification to Practice

Agent Skills are popular for a reason. By defining workflows and even the code to run at each step, they largely solve the problem of unpredictable AI output. This is a huge step forward for productivity.

While Anthropic’s policies may be annoying, their understanding of Agents is truly next level. So the other two of the Big Three have now caught up—Codex and Antigravity both support Agent Skills now.

(Even though they all support it, the directories are different. You can use the Skillsync tool to synchronize them)

An Agent Skill is just a folder containing SKILL.md, and possibly subfolders like scripts/, references/, and so on.

But saying that still doesn’t make it clear what it actually is. After all, subagents, cursor rules, CLAUDE.md, etc., are all markdown files that look similar in format.

The fastest way to understand is to create an agent skill yourself that meets your needs. Anthropic has already done the prep work for us—that’s the skill-creator skill.

Sounds pretty recursive, doesn’t it!

You can open skill-creator/SKILL.md and read it (if you have skillsync installed, you can run skillsync fetch, which will put it in ~/.skillsync/store/anthropics/skills). But you don’t need to read it—you can just start using it.

This article uses the apple-writer skill I created using skill-creator as an example to show how an Agent Skill is built.

The Prompt

I used the following prompt in Antigravity:

Use the skill-creator skill to help me implement an Apple intelligence (e.g., new MacBook, Vision Pro, personnel changes, stocks, etc.) themed WeChat Official Account writing skill. By monitoring major Apple intelligence X, Weibo accounts, and related websites, it should be able to complete 3-5 articles based on events from the past 24 hours. Need to ensure that tracking account configuration is easy to modify.

(Before this, you need to let Antigravity have this skill too. This can be done by running skills sync; its default sync targets include Antigravity)

But AG’s first version wasn’t ideal—it put everything in SKILL.md.

I then opened Claude Code and had GLM4.7 help me refactor according to skill-creator’s requirements. Only then did I get the current version.—Of course, I suspect the same command would work fine if AG refactored it itself.

apple-writer Skill Analysis

Skill Directory Structure

Let’s look at what a complete skill looks like:

skills/apple-writer/
├── SKILL.md                      # Core file: skill definition and workflow
├── sources.json                  # Configuration file: data source configuration
└── references/                   # Auxiliary resource directory
    ├── scraping-guide.md         # Technical guide: scraping implementation details
    └── article-formats.md        # Format specifications: article templates and standards

This structure embodies the Progressive Disclosure design principle recommended by the Agent Skills specification:

• SKILL.md: Concise workflow overview
• Configuration files: Customizable parameters (not required! I added it for easier configuration)
• references/: Detailed technical documentation and specifications

SKILL.md: Core Definition

Now let’s look at the structure of SKILL.md:

---
name: apple-writer
description: "Monitor Apple-related news sources and draft WeChat Official Account articles based on events from the last 24 hours..."
---

# Apple Writer

Gather the latest Apple information and draft articles for WeChat Official Account.

## Configuration

Read `sources.json` to identify targets:
- **Twitter Accounts**: Key opinion leaders and officials to monitor
- **Weibo Keywords**: Topics...
（etc.）

## Workflow

### 1. Gather News (Last 24 Hours Only)

Use Playwright...(etc.)

### 2. Analyze and Synthesize
...

### 3. Draft Articles
...

Configuration File: sources.json

{
  "twitter_accounts": ["MarkGurman", "MingChiKuo", "_AppleHub", "Apple"],
  "weibo_keywords": ["Apple", "iPhone", "MacBook", "Vision Pro"],
  "websites": [
    "https://www.macrumors.com/",
    "https://9to5mac.com/",
    "https://appleinsider.com/"
  ],
  "topics": [
    "MacBook", "Vision Pro", "Personnel Changes", "Stocks", "New Products"
  ]
}

This design of separating configuration makes the skill easier to maintain and customize.

I’ve removed the specific workflow content. Because with the prompt above, anyone can instantly get their own version, which will be roughly the same.

Note that this configuration file was created by the LLM calling on “world knowledge” to find Apple news influencers—I didn’t participate. The actual results are pretty good.

Auxiliary Resources: references/

scraping-guide.md provides detailed technical implementation:

# Web Scraping Guide for Apple News

## Workflow

### Step 1: Start Browser
...

Agent Skills Specification Analysis

Now that we’ve seen the example, let’s look at the Agent Skills specification. A standard Skill needs to meet the following requirements:

1. YAML Frontmatter (Required)

---
name: skill-name           # skill unique identifier, lowercase letters and hyphens
description: "Detailed description of the skill's functionality and use cases. This is key information for Claude to determine when to use this skill. Should include: (1) Main functionality, (2) Use cases, (3) Trigger keywords"
---

Key Points:

• name: kebab-case naming, concise and clear
• description: As detailed as possible, including multiple expressions and use cases—this directly impacts the skill’s discoverability

2. Body Content Organization

The body content of a Skill should follow a clear structure:

# Skill Name

Brief description (optional)

## Configuration (if applicable)

Explain configuration files and parameters

## Workflow

### Step 1: Action Name
Specific instructions and explanations

### Step 2: Action Name
...

## Output (optional)

Explain output format and requirements

3. Progressive Disclosure

This is the core design principle emphasized by Anthropic—

1. Writing the purpose clearly in the frontmatter helps Agents discover this skill;
2. Writing the main workflow clearly in SKILL.md helps Agents understand, or allows answering questions about this skill when users ask.
3. Only when actually using this skill to complete a task will the contents of references/ and scripts/ be loaded.

graph LR
    A[SKILL.md<br/>Concise workflow] --> B{Need detailed info?}
    B -->|Yes| C[references/<br/>Detailed docs]
    B -->|No| D[Execute directly]
    C --> E[Load resources on demand]

The biggest advantage of this approach is saving context usage and reducing token consumption.

Core Elements Comparison

Let’s compare this iterated apple-writer skill with the Agent Skills specification:

Alright, that’s it for today. There’s still enough time before the day ends to complete your first agent skill. Go for it! 😁