AgentSkillsCN

agent-skills

在创建、封装或分发代理技能时使用。涵盖 SKILL.md 规范、Frontmatter 架构、命名规范、市场发布，以及 skills-ref 验证器。 适用场景：创建 SKILL.md 文件、封装可复用的代理能力、市场发布、Frontmatter 架构验证。 切勿用于：项目级别的代理指导（使用 agents-md）、代理运行时配置（使用 ADL 或 Cagent）。

SKILL.md
--- frontmatter
name: agent-skills
description: |
    Use when creating, packaging, or distributing Agent Skills. Covers the SKILL.md specification, frontmatter schema, naming conventions, marketplace publishing, and the skills-ref validator.
    USE FOR: creating SKILL.md files, packaging reusable agent capabilities, marketplace publishing, frontmatter schema validation
    DO NOT USE FOR: project-level agent guidance (use agents-md), agent runtime configuration (use adl or cagent)
license: MIT
metadata:
  displayName: "Agent Skills Standard"
  author: "Tyler-R-Kendrick"
compatibility: claude, copilot, cursor

Agent Skills

Overview

Agent Skills is an open standard from Anthropic for packaging reusable capabilities that AI agents can discover and load dynamically. A skill is a directory containing a SKILL.md file with YAML frontmatter metadata and Markdown instructions. Adopted by Claude, VS Code Copilot, OpenAI Codex, Cursor, and 25+ platforms.

Skill Structure

code
my-skill/
  SKILL.md          # Required — metadata + instructions
  scripts/          # Optional — executable scripts
  references/       # Optional — reference documents
  assets/           # Optional — supporting files

SKILL.md Format

markdown
---
name: my-skill
description: "Use when working with My Framework to follow best practices."
license: MIT
metadata:
  displayName: "My Skill"
  category: frameworks
  author: your-name
compatibility:
  - claude
  - copilot
allowed-tools:
  - Bash
  - Read
  - Edit
---

# My Skill

## Overview
Instructions for the agent when this skill is activated...

## Best Practices
- Concrete guidance the agent should follow
- Code examples demonstrating correct usage

Required Frontmatter

FieldTypeRules
namestringMust match directory name. Lowercase, hyphens, digits only. Max 64 chars.
descriptionstringWhat the skill does and when to trigger it.

Optional Frontmatter

FieldTypeDescription
licensestringSPDX identifier (e.g., MIT, Apache-2.0)
metadataobjectArbitrary key-value pairs (category, author, tags)
compatibilitylistTarget platforms
allowed-toolslistTools the skill may use

Description Best Practices

The description field is critical for discovery — agents use it to decide when to activate the skill:

  • •Start with a trigger phrase: "Use when working with X…"
  • •Be specific: "Use when configuring ASP.NET Core middleware" not "Web development skill"
  • •Keep it under 200 characters

Content Guidelines

  • •Keep the main SKILL.md under 500 lines (~5000 tokens)
  • •Use concrete code examples, not abstract descriptions
  • •Include "do this, not that" guidance
  • •Structure with clear headings for scanability

Validation

bash
# Install the validator
pip install skills-ref

# Validate a skill
agentskills validate path/to/my-skill

# Read properties as JSON
agentskills read-properties path/to/my-skill

# Generate agent prompt XML
agentskills to-prompt path/to/my-skill

Marketplace Publishing

Skills can be published to marketplace repositories:

bash
# Add skills from a marketplace
npx skills add owner/repo

# List available skills
npx skills list owner/repo

The marketplace catalog is defined in .claude-plugin/marketplace.json.

Best Practices

  • •One skill per concept — keep skills focused on a single framework, tool, or pattern.
  • •Use trigger phrases in descriptions so agents activate the skill at the right time.
  • •Validate with agentskills validate before publishing.
  • •Pin the skill name to the directory name — the validator enforces this.
  • •Include runnable code examples that agents can adapt, not just documentation.
  • •Keep instructions actionable: "Do X when Y" rather than "X is a feature of Y."