skill-awesome

When to use this skill

ALWAYS use this skill when you need to know:

• What the Agent Skills specification requires (directory structure, SKILL.md format, frontmatter fields)
• What naming conventions to follow for a skill (name must match directory, lowercase + hyphens only, etc.)
• What frontmatter fields are required vs optional, and their constraints
• What progressive disclosure means and how to structure a skill to use it
• What the official best practices say about scope, context budgeting, gotchas, and checklists
• How to write a good description that triggers reliably
• What script safety rules apply (non-interactive, --help, no secrets, structured output)
• How the TRACE evaluation framework judges skill quality
• What a well-structured skill looks like (reference examples)
• "设计技能" (design a skill), "创建技能" (create a skill), "技能规范" (skill specification)
• "技能命名规则" (skill naming rules), "技能命名规范" (skill naming conventions)
• "SKILL.md 怎么写" (how to write SKILL.md), "frontmatter 规范" (frontmatter specification)
• "技能最佳实践" (skill best practices), "技能目录结构" (skill directory structure)
• "渐进式披露" (progressive disclosure), "Agent Skills 规范" (Agent Skills spec)
• "怎么写 description" (how to write description), "skill description 怎么写"
• "技能脚本安全" (skill script safety), "技能触发条件" (skill trigger conditions)

Trigger phrases include:

• "我要设计一个新的 Skill，告诉我规范" (I want to design a new skill, tell me the spec)
• "SKILL.md 的 frontmatter 有哪些字段" (what fields are in SKILL.md frontmatter)
• "技能的 name 有什么命名规则" (what are the naming rules for skill name)
• "怎么让技能的 description 触发更准确" (how to make skill description trigger more accurately)
• "技能的最佳实践有哪些" (what are the best practices for skills)
• "渐进式披露怎么用" (how to use progressive disclosure)
• "设计一个 Skill 需要注意什么" (what to pay attention to when designing a skill)
• "tell me the Agent Skills specification", "what makes a good skill"
• "how should I structure a skill directory", "skill frontmatter rules"

1. Agent Skills Specification

1.1 Directory Structure

Every skill is a folder containing at minimum a SKILL.md file:

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

1.2 SKILL.md Format

The SKILL.md file must contain YAML frontmatter followed by Markdown body.

Required frontmatter fields

Optional frontmatter fields

Name field rules (detailed)

VALID names:
  mermaid              ✅ lowercase only
  roll-dice            ✅ lowercase + hyphen
  skill-awesome        ✅ lowercase + hyphen

INVALID names:
  My-Skill             ❌ uppercase
  -skill               ❌ starts with hyphen
  skill-               ❌ ends with hyphen
  skill--awesome       ❌ consecutive hyphens
  skill_name           ❌ underscore
  123skill             ❌ starts with digit (no, actually digits ARE allowed)

Body content rules

• No format restrictions — write whatever helps the agent perform the task.
• Keep SKILL.md under 500 lines / 5000 tokens. Move detailed reference material to references/.
• Recommended sections: step-by-step instructions, examples of inputs and outputs, common edge cases.

1.3 Progressive Disclosure

Agents load skills progressively in three stages:

Key implications for skill design:

• The description carries the entire burden of triggering — if it doesn't convey when the skill is useful, the agent won't know to reach for it.
• Keep SKILL.md focused on core instructions. Tell the agent when to load reference files, not just that they exist: "Read references/api-errors.md if the API returns a non-200 status code."
• Avoid deeply nested reference chains — keep references one level deep from SKILL.md.

2. Best Practices for Skill Design

2.1 Start from Real Expertise

Do NOT ask an LLM to generate a skill from its general training knowledge — this produces vague, generic procedures. Ground skills in real, domain-specific context:

• Extract from a hands-on task: Complete a real task, then extract the reusable pattern. Capture steps that worked, corrections you made, input/output formats, and project-specific context.
• Synthesize from existing project artifacts: Internal documentation, runbooks, API specifications, code review comments, version control history, real-world failure cases.

2.2 Spend Context Wisely

Every token in your skill competes for the agent's attention.

Ask yourself about each piece of content: "Would the agent get this wrong without this instruction?" If no, cut it.

2.3 Calibrate Control

Match the specificity of instructions to the fragility of the task:

2.4 Effective Instruction Patterns

Gotchas sections — the highest-value content in many skills. Environment-specific facts that defy reasonable assumptions:

## Gotchas
- The `users` table uses soft deletes. Queries must include `WHERE deleted_at IS NULL`.
- The user ID is `user_id` in the database, `uid` in the auth service, and `accountId` in the billing API. All three refer to the same value.

Output format templates — more reliable than prose descriptions. Agents pattern-match well against concrete structures:

## Report structure
Use this template, adapting sections as needed:

# [Analysis Title]
## Executive summary
[One-paragraph overview]
## Key findings
- Finding 1 with supporting data
## Recommendations
1. Specific actionable recommendation

Checklists for multi-step workflows — helps the agent track progress and avoid skipping steps:

## Workflow
- [ ] Step 1: Analyze input
- [ ] Step 2: Create plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output

Validation loops — instruct the agent to validate before proceeding:

1. Make your edits
2. Run validation: `python scripts/validate.py output/`
3. If validation fails: review error, fix issues, re-run validation
4. Only proceed when validation passes

2.5 "When to use" / "When NOT to use" sections

Include a clear "When NOT to use" section with near-miss boundaries — scenarios that share keywords or concepts with your skill but need a different skill. This prevents false triggering.

3. Description Optimization

3.1 Principles for Effective Descriptions

3.2 Testing Description Triggering

Create eval queries (~20) — realistic user prompts labeled with whether they should or shouldn't trigger your skill. Design:

• Should-trigger queries: Vary phrasing (formal/casual/typos), explicitness (naming the domain vs describing the need), detail level, and complexity.
• Should-not-trigger queries: Focus on near-misses — queries that share keywords with your skill but actually need something different. These are the most valuable negative test cases.

Run each query 3+ times (model behavior is nondeterministic) and compute a trigger rate. Use a train/validation split (60%/40%) to avoid overfitting.

4. Script Safety Guidelines

When a skill bundles executable scripts in scripts/ or instructs the agent to run shell commands:

Required

Recommended

Self-contained scripts (recommended pattern)

Use inline dependency declarations so scripts can run with a single command:

• Python (PEP 723): # /// script / # dependencies = [...] / # /// → run with uv run
• Deno: import from "npm:package@version" → run with deno run
• Bun: import from "package@version" → run with bun run

5. Evaluation Frameworks

5.1 Official Rubric (agentskills.io)

Five inspection dimensions from the official specification:

5.2 TRACE Model (SkillHub)

Five-dimension quality model for evaluating skills:

6. Complete Skill Creation Checklist

When designing a new skill, verify all of the following:

Structure

• Directory name uses lowercase letters, digits, and hyphens only
• name in frontmatter matches directory name exactly
• SKILL.md exists at the skill root
• Optional directories follow conventions (scripts/, references/, assets/)

Frontmatter

• name is 1-64 characters, lowercase + hyphens only, no leading/trailing hyphens, no consecutive hyphens
• description is 1-1024 characters, describes both what AND when to use
• description uses imperative phrasing ("Use when...")
• license field present (short name or reference to bundled license file)

Body content

• Under 500 lines / 5000 tokens
• Step-by-step instructions are clear and actionable
• Examples of inputs and outputs provided
• Common edge cases documented
• Gotchas section for non-obvious facts
• "When NOT to use" section with near-miss boundaries

Progressive disclosure

• Long reference material moved to references/
• References linked with clear "when to read" triggers
• No deeply nested reference chains

Scripts (if applicable)

• Non-interactive — no TTY prompts
• --help prints usage and examples
• Error messages say what failed and what to try
• No hardcoded secrets
• Destructive operations require --force/--confirm
• Structured output option (--format json)

Trigger quality

• Description uses user-intent language
• Both "should trigger" and "should not trigger" scenarios considered
• Near-miss boundaries defined for adjacent skills

References

This knowledge is distilled from official sources. For the full original content, see:

• agentskills.io Specification
• Best practices for skill creators
• Optimizing skill descriptions
• Evaluating skill output quality
• Using scripts in skills
• How to create custom Skills (Claude)
• SkillHub TRACE Evaluation

For auto-generating an awesome list index from a skills repository, use the companion script:

python3 scripts/build_awesome.py --skills-root <path> --output AWESOME_AGENT_SKILLS.md

For a complete example of what an awesome list looks like, see [examples/sample-awesome.md](examples/sample-awesome.md).

Keywords

English keywords: agent-skills, skill-specification, skill-design, skill-creation, skill-development, skill-best-practices, skill-naming, skill-frontmatter, skill-directory-structure, progressive-disclosure, skill-description, skill-trigger, skill-evaluation, script-safety, trace-evaluation, official-rubric, skill-compliance, skill-checklist, skill-template, how-to-design-a-skill

Chinese keywords (中文关键词): 设计技能, 创建技能, 技能规范, 技能命名规则, 技能命名规范, SKILL.md 怎么写, frontmatter 规范, skill frontmatter, 技能最佳实践, 技能目录结构, 渐进式披露, 怎么写 description, skill description 怎么写, 技能触发条件, 技能脚本安全, 技能评估, TRACE 评测, 技能合规, 技能检查清单, Agent Skills 规范

FAQ

Q1: 如何快速上手此技能？ A: 参考上方的快速开始章节，按步骤操作即可。

Q2: 遇到版本不兼容问题怎么办？ A: 检查依赖版本，使用 lock 文件锁定，参考常见陷阱章节。

Q3: 如何在生产环境使用？ A: 参考最佳实践章节，确保配置正确，做好监控和日志。

Q4: 性能如何优化？ A: 参考性能优化相关文档，使用缓存、索引等手段。

Q5: 如何贡献或反馈问题？ A: 在 GitHub 仓库提交 Issue 或 Pull Request。

Q6: 是否支持中文？ A: 支持中文文档和中文注释，详见国内适配章节。