From Zero to One: Deeply Understanding Agent Skills — Concepts, Structure, and a Construction Guide

Moving Agents from "ad-hoc improvisation" to "stable reuse"

Foreword

As large model capabilities continue to evolve, we are shifting from "can the model answer" to "can the model reliably complete a class of tasks." Against this backdrop, Agent Skills, as an open format, is becoming a key piece in the engineering implementation of AI Agents.

Based on the currently public Agent Skills specification, and combined with engineering practices from Codex, VS Code, Claude Code, and self-developed Agents, this article systematically organizes the concept, directory structure, loading mechanism, construction methods, and implementation of Skills. Whether you are an Agent developer, a business engineer, or a technical decision-maker, this article will help you build a complete cognitive framework for Agent Skills.

1. First, Understand: What Exactly is a Skill?

1.1 A Vivid Analogy

A Skill is not a new model, nor is it an independent API. It is more like an Agent's "loadable work manual":

• Tells the Agent when it should use this capability
• Tells the Agent what steps to follow for execution
• Tells the Agent which scripts it can call
• Tells the Agent how to handle exceptions
• Tells the Agent how to ultimately verify results

1.2 The Four-Layer Architecture of Agent Capabilities

To understand the position of a Skill within the entire system more clearly, we can break down an Agent's capabilities into four layers:

Concept	Problem Solved	Typical Content
Skill	How to reliably complete a class of tasks	Instructions, processes, judgment rules, scripts, reference materials, templates
Tool	How to execute a single action	Read files, call APIs, run commands, write to databases
MCP	How to connect to external capabilities in a standard way	Servers, resources, tools, authorization, and protocol adaptation
Plugin	How to distribute a complete set of extended capabilities	Multiple Skills, MCPs, commands, Hooks, resources, and configurations

Within these four layers: the Model is responsible for understanding and decision-making, the Tool is responsible for executing a single action, MCP is responsible for connecting to external systems, and the Skill is responsible for organizing knowledge, processes, and resources into a repeatable task plan.

⚠️ Key Insight: A Skill typically orchestrates Tools or MCPs, but it is not itself a Tool or MCP.

1.3 When Should You Codify a Skill?

A practical criterion is:

If a type of task occurs repeatedly, and the "sequence of steps, quality standards, boundary conditions, and output format" are more important than ad-hoc improvisation, it is worth codifying into a Skill.

But there is a trend worth watching: as base model capabilities become stronger (Opus 5, GPT-5.6, Kimi 3, etc.), some heavy, cumbersome Skills can actually become shackles for the Agent. We need to write specific Skills based on vertical business needs, which is precisely the deep customization territory that general-purpose Agents cannot reach.

2. The Core Structure of the Current Public Specification

2.1 Complete Directory Structure

The Agent Skills specification defines a clear directory structure, distinguishing between required items, optional specification items, and engineering auxiliary files:

skill-name/
├── SKILL.md                # Required: YAML metadata + Markdown execution instructions
├── agents/                 # Optional: Client extensions
│   └── openai.yaml         # Example: display_name, short_description, default_prompt
├── scripts/                # Optional: Executable scripts, validators, generators
│   ├── extract.py          # Example: Data extraction script
│   └── validate.ps1        # Example: Windows/PowerShell validation script
├── references/             # Optional: Long-form reference materials read on demand
│   ├── REFERENCE.md        # Example: Detailed technical specifications
│   └── decision-table.md   # Example: Decision tables, error codes, or boundary conditions
├── assets/                 # Optional: Templates, images, sample data, configuration skeletons
│   ├── template.md         # Example: Output template
│   └── sample.json         # Example: Input/output samples
├── evals/                  # Optional: Skill triggering and quality evaluation test cases
│   ├── evals.json          # Example: prompt, expected_output, files, assertions
│   └── files/              # Optional: Evaluation input files
│       └── sample.csv
└── LICENSE.txt             # Optional: License file

2.2 Three-Layer Understanding

We can understand the above directory structure from three layers:

• First Layer: The core of the Agent Skills open specification — SKILL.md is required, scripts/, references/, assets/ are optional directories explicitly supported by the specification.
• Second Layer: Client extensions — for example, agents/openai.yaml commonly seen in Codex, used for skill lists and UI display.
• Third Layer: Quality engineering directory — for example, evals/, used to save evaluation test cases, not resources that must be loaded at Skill runtime.

2.3 Design Responsibilities of Each Directory

Each directory has its specific design responsibility:

• scripts/: Carries deterministic operations (scripts)
• references/: Carries longer knowledge (reference materials)
• assets/: Carries static resources (templates, examples)
• evals/: Carries quality verification (evaluation test cases)

⚠️ Notes:

• Directories can be further extended, but avoid directly packaging keys, personal data, or unreviewed executable files into a Skill.
• Outputs generated per evaluation round in evals/, such as grading.json, timing.json, benchmark.json, are recommended to be placed in a separate workspace next to the Skill, do not mix them into the runtime Skill package.
• README.md, CHANGELOG, and installation instructions are better placed at the repository level, rather than letting the Agent treat them as Skill content.

2.4 Skill Structure Panorama

┌─────────────────────────────────────────────────────────────────┐
│                       skill-name/                              │
├─────────────────────────────────────────────────────────────────┤
│  ████████████████████████████████████████████████████████████ │
│  █  SKILL.md          █  Required: Metadata + Workflow       █ │
│  ████████████████████████████████████████████████████████████ │
│                                                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌───────────────┐ │
│  │  scripts/       │  │  references/    │  │  assets/      │ │
│  │  Deterministic  │  │  Long-tail      │  │  Templates &  │ │
│  │  scripts        │  │  knowledge base │  │  static assets│ │
│  └─────────────────┘  └─────────────────┘  └───────────────┘ │
│     Core spec optional    Core spec optional    Core spec optional │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  agents/openai.yaml      Client extension: UI metadata  │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  evals/evals.json        Quality engineering: test cases│  │
│  │  evals/files/            Evaluation input files         │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  LICENSE.txt             Distribution: license file     │  │
│  └─────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

2.5 The Two Parts of SKILL.md

SKILL.md consists of YAML frontmatter and Markdown body:

• Frontmatter: Responsible for allowing the Agent to quickly determine relevance during the "discovery phase"
• Body: Responsible for providing detailed execution instructions during the "activation phase"

Frontmatter Field Descriptions

Field	Required	Current Constraints and Purpose
name	✅ Yes	1-64 characters; use lowercase letters, numbers, and hyphens; cannot start or end with a hyphen; no consecutive hyphens; must match the parent directory
description	✅ Yes	1-1024 characters; describes what the Skill does and when to use it; the primary basis for the Agent to decide whether to activate
license	❌ No	License name, or a pointer to a license file within the Skill
compatibility	❌ No	Environment requirements, e.g., operating system, dependency packages, network access, target client; up to 500 characters
metadata	❌ No	Custom key-value metadata, e.g., author, team, version, change ID
allowed-tools	❌ No	Space-separated list of pre-authorized tools; currently an experimental field, cannot replace a full permission system

What Should the Body Contain?

The body has no mandatory template, but should clearly state task boundaries and executable steps. Recommended content includes:

• ✅ Applicable scenarios
• ✅ Inputs and preconditions
• ✅ Standard workflow
• ✅ Decision branches
• ✅ Output format
• ✅ Exceptions and boundaries
• ✅ Verification steps
• ✅ Relative path references to scripts and reference files

💡 Important Tip: The body is not an encyclopedia. General knowledge, repeated model common sense, and large sections of background introduction increase context costs. The correct approach is:

• Split frequently changing, lengthy materials into references/
• Hand deterministic calculations or mechanical operations to scripts/
• Hand fixed formats to assets/

3. Loading Method: Progressive Disclosure

3.1 Core Design Philosophy

The key design of the current specification is Progressive Disclosure, which divides Skill content into three layers of loading:

Layer	Content Loaded	When It Happens	Design Goal
1. Catalog (Discovery)	name + description, plus path if necessary	At session start or Skill scan	Let the Agent know what capabilities exist, without consuming full context upfront
2. Instructions (Activation)	Full SKILL.md body	After a task matches the description	Inject the process and rules needed for this task into the Agent
3. Resources (Execution)	Specific files in scripts/, references/, assets/	When the body explicitly references them and the task genuinely needs them	Only load the resources needed for the current step

3.2 Progressive Loading Chain Diagram

User Task
    │
    ▼
┌─────────────────────────────────────┐
│  Catalog                            │
│  Scan name + description            │
└─────────────────────────────────────┘
    │
    ▼
Does description match?
    │
    ├── No ──► Continue normal Agent flow
    │
    └── Yes
         │
         ▼
┌─────────────────────────────────────┐
│  Instructions                       │
│  Read SKILL.md                      │
└─────────────────────────────────────┘
    │
    ▼
Does current step need resources?
    │
    ├── No ──► Execute according to workflow
    │
    └── Yes
         │
         ▼
┌─────────────────────────────────────┐
│  Resources                          │
│  Read scripts / references /        │
│  assets on demand                   │
└─────────────────────────────────────┘
    │
    ▼
Call Tool / MCP
    │
    ▼
Execute, verify, and log risks
    │
    ▼
Output results and next steps

📌 When reading this diagram, grasp one key point: A Skill does not stuff all content into the context at once, but first completes discovery with a short description, then unfolds layer by layer only when truly relevant.

4. Where Are Skills Usually Placed?

The Agent Skills specification defines the Skill file format, but does not mandate a single installation directory for all clients. The most common convention in actual projects is to use .agents/skills/:

Scope	Suggested Path	Applicability
Project-level	<project>/.agents/skills/<skill-name>/	Only effective for the current repository or project; suitable for business rules and repository workflows
User-level	~/.agents/skills/<skill-name>/	Reusable across multiple projects for the current user; suitable for general development, writing, and operations workflows
Client-native directory	Defined by the specific Agent product	Can provide additional capabilities, but cross-client reusability depends on implementation
Organization-level or built-in directory	Provided by deployment platform, plugin, or management side	Suitable for enterprise standard processes, compliance checks, and team-shared capabilities

Priority Rules

If Skills with the same name exist simultaneously, a deterministic priority is recommended:

Project-level > User-level > Built-in defaults

Within the same scope, a fixed ordering rule should also be established, and conflict alerts should be logged.

⚠️ Security Note: Project-level Skills come from code repositories and may be untrusted content. Production-grade Agents should perform project trust judgments before loading.

5. How to Build a Skill from Scratch

💡 Practical Experience: Generally, use the skill-creator Skill of a SOTA Agent to assist in creation. Skills written by humans are prone to many problems and omissions. The engineer's responsibility is to plan the Skill's architecture and review whether the Skill meets expectations.

5.1 Step 1: Choose a Sufficiently Narrow Task

❌ Don't start with "help me with all backend development"

✅ Better entry points:

• "Review changes to Go HTTP services"
• "Generate interface tests for Java services"
• "Convert meeting minutes into trackable tasks"

🎯 Core Principle: A Skill cannot be broad; it must be written for a sufficiently vertical, sufficiently narrow scenario. The description must be clear enough for the Agent to easily select this Skill.

5.2 Step 2: Write the Trigger Description First, Then the Body

First, answer two questions in one sentence:

1. What does this Skill do?
2. Under what circumstances would a user need it?

The description should include synonyms and typical inputs, but do not stuff the complete workflow into the description.

5.3 Step 3: Write the Workflow as Steps the Agent Can Execute

Each step should try to include: Action + Judgment Basis + Next Step

❌ Don't just write:

"Check carefully to ensure quality"

✅ Instead, write:

"First read the change scope, then run the specified tests; if tests fail, retain the error output and stop the release"

⚠️ High-Risk Operations: For high-risk actions involving writes, deletes, sending messages, deployments, etc., explicitly require previews, confirmations, idempotency keys, rollbacks, or human approval.

5.4 Step 4: Split Resources as Needed

• scripts/: Place programs with strong determinism and worth reusing (data extraction, format checking, report generation, etc.). Scripts should have clear inputs, outputs, error messages, and dependency descriptions.
• references/: Place longer domain specifications, API conventions, error codes, examples, and decision tables. The body only references specific files when needed.
• assets/: Place templates, sample data, icons, configuration skeletons, and other static resources.

5.5 Step 5: Verify the Skill, Not Just the Text

Prepare at least one set of:

• ✅ Positive triggers
• ✅ Negative non-triggers
• ✅ Boundary conditions
• ✅ Abnormal inputs

Verify whether the Agent:

• Activates the Skill on the correct tasks
• Actually reads the scripts or reference materials
• Adheres to the output format
• Stops within safe boundaries upon failure

Verification Toolchain:

• Basic level: Use skills-ref validate ./my-skill to check directories, frontmatter, and naming constraints
• Quality level: Maintain 2-3 real test cases in evals/evals.json, running with-skill versus without-skill (or old version) for comparison

5.6 Step 6: Versioning and Maintenance

• Put the Skill into Git
• Write clear reasons and impact scope for changes
• When workflows, tool interfaces, dependency versions, or security rules change, synchronously update the body, scripts, and test samples
• Especially perform regression testing on description modifications, as they directly affect activation recall

6. A Directly Copyable Minimal Example

Below is an example for Go service change review. It deliberately stays short, leaving detailed rules for subsequent references/ files.

Directory Structure

go-review/
├── SKILL.md
├── scripts/
│   └── check-coverage.sh
├── references/
│   ├── go-coding-standards.md
│   └── common-bugs.md
└── assets/
    └── review-template.md

SKILL.md Example

---
name: go-review
description: Review changes to Go HTTP services, checking code standards, test coverage, and potential bugs. Suitable for Go service PR reviews or pre-commit code checks.
license: MIT
compatibility: Go 1.21+, Linux/macOS
metadata:
  author: platform-team
  version: 1.0.0
---

# Go HTTP Service Change Review

## Applicable Scenarios
- Pull Request review for Go services
- Quality gate before code commit

## Input
- List of changed files (Git diff)
- Target branch name

## Workflow

1. Read `git diff` to get the change scope
2. Run `go vet` on each changed `.go` file
3. Check if test coverage has dropped by more than 2%
4. Check code standards against `references/go-coding-standards.md`
5. Output the review report to `assets/review-template.md`

## Exception Handling
- If `go vet` fails, output error details and stop the workflow
- If coverage drops by more than 2%, mark as requiring manual review

## Verification
- Run `scripts/check-coverage.sh` to verify the coverage report

7. If You Are Building Your Own Agent: How to Implement Skill Support

A self-developed Agent does not need to make Skills into a complex plugin system. A minimal implementation can revolve around seven links:

7.1 Seven Core Links

Link	Description	Key Points
1. Discovery	Scan project-level, user-level, and organization-level directories	Only identify subdirectories containing SKILL.md; skip directories like .git, node_modules; set maximum depth and quantity limits
2. Parsing	Read YAML frontmatter	At minimum, extract name, description, and the absolute path of SKILL.md; log diagnostics on parse failure; Skills missing description should not enter the catalog
3. Build Catalog	Provide name, description, path, and Skill root directory to the model	The catalog should be short; do not inject all Skill bodies into the context at once
4. Activation	Prioritize letting the model judge relevance based on description	Then read the full SKILL.md; can also provide an explicit activate_skill tool to support user-named activation
5. Resource Access	Resolve relative paths in the body against the Skill root directory	Read scripts, references, and assets on demand; do not load the entire directory by default
6. Permissions & Trust	Perform trust judgment on project-level Skills	Implement permission control for scripts, network, file writes, and high-risk commands; do not treat allowed-tools as the sole security boundary
7. Observability	Log discovery, conflicts, activation, resource reads, script execution, and failure reasons	Facilitates explaining "why a certain Skill was used or not used"

7.2 Implementation Pseudocode

# 1. Discovery
catalog = discover(project_dirs, user_dirs, org_dirs)

# 2. Parsing
catalog = parse_frontmatter(catalog)

# 3. Filtering
catalog = filter_by_trust_and_policy(catalog)

# 4. Catalog Injection
model_context.add(skill_catalog(catalog))

# 5. Activation and Execution
if model_or_user_selects(skill):
    instructions = load(skill.SKILL.md)
    model_context.add(instructions)
    resources = resolve_referenced_files(skill.root)
    run_only_the_resources_needed_for_current_step(resources)

7.3 Design Principles

📌 The implementation of a self-developed Agent should separate "format compatibility" from "product features":

• The Agent Skills specification defines the general conventions for directories, SKILL.md, and progressive loading
• Specific clients can add their own installation paths, explicit commands, permission models, lifecycle hooks, or packaging methods
• But these extensions must not break the portability of the minimal format

8. Common Failure Modes and Improvement Suggestions

Problem	Manifestation	Improvement Suggestion
description too broad	False triggers when tasks increase; Agent doesn't know the boundaries	Add clear objects, actions, inputs, and applicable scenarios; split into multiple Skills if necessary
SKILL.md too long	Context bloats after activation; key steps are drowned out	Keep the workflow in the body; migrate long specifications to references/; body is recommended to be controlled within about 5000 tokens
Only principles, no actions	Wrote "ensure safety" but didn't explain how to preview, confirm, and rollback	Rewrite quality requirements as executable checks, commands, decision branches, and output formats
Scripts not reproducible	Depend on hidden environment variables, current directory, or undocumented third-party packages	Document dependencies, use explicit parameters, provide error messages and exit codes, and add sample tests
Treating Skill as a permission system	Skill says "can execute a certain command," so security controls are bypassed	The Harness should enforce least privilege, path restrictions, approval, timeouts, auditing, and cancellation at the tool layer
No negative testing	Any task containing keywords triggers the Skill	Add similar but should-not-trigger prompts; verify recall rate and false trigger rate

9. Pre-Release Checklist

Before releasing a Skill, please confirm item by item:

• SKILL.md's name matches the parent directory and conforms to naming constraints
• description clearly states what the Skill does and when to use it (1-1024 characters)
• The body contains executable steps, not vague principles
• Long-form content has been split into references/
• Scripts in scripts/ have clear input, output, and dependency descriptions
• At least 2-3 evals/ test cases have been prepared (including positive and negative)
• High-risk operations have explicit preview, confirmation, or rollback mechanisms
• No hardcoded keys or personal data in the Skill
• Passed basic checks with skills-ref validate
• With-skill vs without-skill comparison tests have been done
• Git commit message clearly states the reason and impact scope of changes

10. Conclusion: Treat Skills as Testable "Process Products"

Agent Skills is essentially an engineering framework for making tacit knowledge explicit, and making explicit knowledge executable. It is not complex, but it requires us to shift our thinking across several dimensions:

1. From "writing prompts" to "designing processes" : A Skill is not just instructions for the model, but a complete set of operational specifications
2. From "one-off" to "reusable" : Every Skill should be tested, version-managed, and continuously optimized
3. From "big and comprehensive" to "small and precise" : Vertical, narrow-scenario Skills are easier to trigger and execute correctly
4. From "model dependency" to "process assurance" : Skills return deterministic operations to scripts, judgment logic to rules, and knowledge to reference materials

🎯 Ultimate Goal: Treat Skills as testable "process products" , not as a prompt that says "just wing it." This is a key step for Agents to move from "cool demos" to "production-grade tools."

---

This article is organized based on the Agent Skills public specification updated on 2026-08-02, and incorporates engineering practices from Codex, VS Code, Claude Code, and self-developed Agents.