agentskills-io

按照agentskills.io 的官方开放标准创建、验证和发布代理技能。在以下情况下使用：(1) 为 AI 代理创建新技能；(2) 验证技能结构和元数据；(3) 了解代理技能规范；(4) 将现有文档转换为可移植技能；或 (5) 确保与 Claude Code、Cursor、GitHub Copilot 和其他工具的跨平台兼容性。

## 概述（中文）

按照agentskills.io 的官方开放标准创建、验证和发布代理技能。在以下情况下使用：(1) 为 AI 代理创建新技能；(2) 验证技能结构和元数据；(3) 了解代理技能规范；(4) 将现有文档转换为可移植技能；或 (5) 确保与 Claude Code、Cursor、GitHub Copilot 和其他工具的跨平台兼容性。

## 原文

# Agent Skills (agentskills.io)

Create portable skills for AI agents. Works with Claude Code, Cursor, GitHub Copilot, OpenAI integrations, VS Code (symlinks enable sharing across tools).

## Resources
- Specification: https://agentskills.io/specification | Validator: https://github.com/agentskills/agentskills

## Structure
```
skill-name/
├── SKILL.md          # Required (frontmatter + instructions, <5000 tokens activation)
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed docs
└── assets/           # Optional: templates, static files
```

**Rules**: Dir name = frontmatter `name:`. Only 3 subdirs. SKILL.md <500 lines. ~100 tokens for discovery (name+desc).

## Frontmatter

### Required
- `name`: 1-64 chars, lowercase alphanumeric-hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`)
- `description`: 1-1024 chars, include "Use when..." (discovery budget: ~100 tokens)

### Optional
- `license`: SPDX identifier (Apache-2.0, MIT) | `compatibility`: Environment reqs (<500 chars)
- `metadata`: Key-value pairs (author, version, tags) | `allowed-tools`: Space-delimited tool list

## Validation
```bash
# Install permanently (vs ephemeral uvx)
uv tool install git+https://github.com/agentskills/agentskills#subdirectory=skills-ref
# Or use uvx for one-shot validation
uvx --from git+https://github.com/agentskills/agentskills#subdirectory=skills-ref skills-ref validate ./skill
```

| Command | Description |
|---------|-------------|
| `skills-ref validate <path>` | Check structure, frontmatter, token budgets |
| `skills-ref read-properties <path>` | Extract metadata |
| `skills-ref to-prompt <path>` | Generate prompt format |

## Writing Rules
- Imperative language: "Check: `command`" not "You might want to..."
- Concrete examples with expected output; handle common errors with solutions
- Progressive disclosure: core in SKILL.md (<5000 tokens), details in references/

## Common Errors

| Error | Fix |
|-------|-----|
| Invalid name | Lowercase alphanumeric-hyphens only |
| Missing description | Add `description:` field with "Use when..." |
| Description too long | <1024 chars, move details to body |
| Invalid YAML | Check indentation, quote special chars |
| Missing SKILL.md | Filename must be exactly `SKILL.md` |
| Dir name mismatch | Directory name must match `name:` field |

## Quick Workflow
1. Create: `mkdir skill-name && touch skill-name/SKILL.md`
2. Add frontmatter (name, description with "Use when...")
3. Write instructions (bullets, not prose); validate: `skills-ref validate ./skill-name`
4. Test with AI agent, iterate; add LICENSE, push to repository

## Plugin Structure (Claude Code)
```
plugin-name/
├── .claude-plugin/plugin.json
├── README.md, LICENSE, CHANGELOG.md  # CHANGELOG.md tracks versions
├── skills/skill-name/SKILL.md
├── agents/     # Optional: subagents (.md files)
└── examples/   # Optional: full demo projects
```

**Distinctions**: Plugin `examples/` = runnable projects. Skill `assets/` = static resources only.

## Batch Validation & Versioning
```bash
bash scripts/validate-skills-repo.sh     # Validate all skills in repo
bash scripts/bump-changed-plugins.sh     # Auto-bump only changed plugins (semver)
```

## Minimal Example
```yaml
---
name: example-skill
description: Brief description. Use when doing X.
---
# Example Skill
## Prerequisites
- Required tools
## Instructions
1. First step: `command`
2. Second step with example
## Troubleshooting
**Error**: Message → **Fix**: Solution
```

## Symlink Sharing
Share skills across Claude Code, Cursor, VS Code: `ln -s /path/to/skills ~/.cursor/skills`

## References
- [specification.md](references/specification.md) - Full YAML schema, token budgets
- [examples.md](references/examples.md) - Complete examples across platforms
- [validation.md](references/validation.md) - Error troubleshooting
- [best-practices.md](references/best-practices.md) - Advanced patterns, symlink setup