shield_lock
金大哥
联系我们
← 返回 Skill 列表
extension
分类: AI Agent 能力无需 API Key

agentskills

Agent Skills 开放标准参考（agentskills.io）。在为 Claude Code、Cursor、Gemini CLI、OpenAI Codex、VS Code、Roo Code 以及 20 多个兼容代理创建可移植技能时使用。涵盖前置元数据模式、命名规则、目录结构、逐步公开、验证和编写。在创建跨代理技能之前加载。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

Agent Skills Open Standard

The Agent Skills format is an open standard for extending AI agent capabilities with specialized knowledge and workflows. Originally developed by Anthropic, adopted by 25+ agent products.

Source: https://agentskills.io

When to use this skill: Before creating any skill that should be portable across multiple agent products. For Claude Code-specific features (hooks, context fork, model selection, invocation control), see claude-skills-overview-2026 instead.

SKILL.md Format

Every skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown body:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation loaded on demand
└── assets/           # Optional: templates, images, data files

Required Frontmatter

---
name: skill-name
description: What this skill does and when to use it.
---

Optional Frontmatter Fields

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Requires git, docker, jq, and access to the internet
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

Field Reference

| Field | Required | Max Length | Constraints | | --------------- | -------- | ---------- | ---------------------------------------------------------------- | | name | Yes | 64 chars | Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. Must match directory name. | | description | Yes | 1024 chars | Non-empty. Describe what + when to use. Include trigger keywords. | | license | No | — | License name or reference to bundled file. | | compatibility | No | 500 chars | Environment requirements (products, packages, network). | | metadata | No | — | Arbitrary string key-value pairs. | | allowed-tools | No | — | Space-delimited pre-approved tools. Experimental. |

Name Validation Rules

  • 1-64 characters
  • Unicode lowercase alphanumeric and hyphens only (a-z, 0-9, -)
  • Must not start or end with -
  • Must not contain consecutive hyphens (--)
  • Must match the parent directory name

Valid: pdf-processing, data-analysis, code-review Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive)

Description Guidelines

Write in third person. Include both what the skill does and when to use it.

# Good — specific, includes triggers
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Weak — vague, no triggers
description: Helps with PDFs.

Preferred patterns: Use gerund form (processing-pdfs) or noun phrases (pdf-processing). Prefer descriptive names like pdf-processing over generic names like helper or utils.

Progressive Disclosure

Skills use three-level loading to manage context efficiently:

  1. Metadata (~100 tokens): name + description loaded at startup for all skills
  2. Instructions (<5000 tokens recommended): Full SKILL.md body loaded on activation
  3. Resources (as needed): Files in scripts/, references/, assets/ loaded on demand

Keep SKILL.md body lean. Move detailed reference material to separate files. Run uvx skilllint@latest check <skill-path> after writing and follow its guidance on token-based sizing.

Disclosure Patterns

Pattern 1 — High-level guide with references:

# PDF Processing

## Quick start
[core example]

## Advanced features
- **Form filling**: See [references/forms.md](references/forms.md)
- **API reference**: See [references/api.md](references/api.md)

Pattern 2 — Domain-specific organization:

bigquery-skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Pattern 3 — Conditional details:

For simple edits, modify XML directly.
**For tracked changes**: See [references/redlining.md](references/redlining.md)

Rules:

  • Keep file references one level deep from SKILL.md — link directly from SKILL.md so the agent can discover content without following long chains
  • For files >100 lines, include a table of contents at the top

Directory Contents

scripts/

Executable code agents can run. Should be self-contained, include helpful error messages, handle edge cases. Scripts save tokens (no code generation needed) and ensure consistency.

Make execution intent clear:

  • "Run scripts/extract.py to extract fields" (execute)
  • "See scripts/extract.py for the algorithm" (read as reference)

references/

Documentation loaded on demand. Keep individual files focused — smaller files mean less context usage. Structure files >100 lines with a table of contents.

assets/

Static resources used in output (templates, images, data files). Not loaded into context — used by the agent in its output.

Authoring Best Practices

For the complete Anthropic authoring guide, see references/best-practices.md.

Key principles:

  1. Concise is key — Reason: Claude is already smart. Include only context it doesn't have. Prefer concise examples over verbose explanations to keep the skill discoverable and efficient.
  2. Set appropriate degrees of freedom — Reason: Match specificity to task fragility. High freedom for open-ended tasks; low freedom for fragile operations.
  3. Use workflows for complex tasks — Reason: Clear sequential steps with checklists help agents track progress and complete multi-step work reliably.
  4. Implement feedback loops — Reason: Run validator, fix errors, repeat. Validators surface issues early so agents correct before proceeding.
  5. Test with all target models — Reason: Haiku may need more detail than Opus; testing across models ensures the skill works for all targets.
  6. Build evaluations first — Reason: Evaluations identify real gaps before documentation. Create them before writing extensively so the skill addresses actual failures.

What to Include

Focus skill content on:

  • Instructions the agent needs to perform the task
  • Step-by-step workflows, examples, and edge cases
  • References to scripts/, references/, and assets/ for details

Place user-facing docs (README, CHANGELOG, INSTALLATION_GUIDE), setup procedures, and time-sensitive details in a separate "Legacy patterns" section or external docs. Claude already knows general concepts — include only skill-specific information.

Validation

Use the skills-ref reference library to validate:

# Validate a skill directory
skills-ref validate ./my-skill

# Read skill properties as JSON
skills-ref read-properties ./my-skill

# Generate <available_skills> XML for agent prompts
skills-ref to-prompt ./skill-a ./skill-b

Python API:

from pathlib import Path
from skills_ref import validate, read_properties, to_prompt

problems = validate(Path("my-skill"))
props = read_properties(Path("my-skill"))
prompt = to_prompt([Path("skill-a"), Path("skill-b")])

Install: pip install -e . from the skills-ref directory.

Portable vs Claude Code-Specific

The open standard defines a portable subset. Claude Code extends it with additional frontmatter fields.

| Feature | Open Standard | Claude Code Extension | | ------------------------ | ------------- | --------------------- | | name | Yes | Yes | | description | Yes | Yes | | license | Yes | Yes | | compatibility | Yes | Yes | | metadata | Yes | Yes | | allowed-tools | Yes (experimental) | Yes (extended syntax) | | argument-hint | No | Yes | | model | No | Yes | | context: fork | No | Yes | | agent | No | Yes | | user-invocable | No | Yes | | disable-model-invocation | No | Yes | | hooks | No | Yes |

For portable skills: Use only the open standard fields. Other agents will ignore unknown fields, but keeping frontmatter clean improves compatibility.

For Claude Code skills: See claude-skills-overview-2026 for the full extended schema.

Detailed References

External Links