Back to Details

skill-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Authoring Guide

技能编写指南

This skill provides guidance for writing Agent Skills that comply with the agentskills.io specification.
本技能提供符合agentskills.io规范的Agent Skills编写指导。

When to Use

适用场景

  • Creating a new skill for this repository
  • Reviewing a skill PR for compliance
  • Checking if an existing skill follows best practices
  • Understanding token budgets and progressive disclosure
  • 为当前仓库创建新技能
  • 审核技能PR的合规性
  • 检查现有技能是否遵循最佳实践
  • 了解令牌预算与渐进式披露机制

Constraints

约束条件

  • name
    : 1-64 chars, lowercase + hyphens, match directory
  • description
    : 1-1024 chars, explain WHAT and WHEN
  • SKILL.md: <500 tokens (soft), <5000 (hard)
  • references/*.md: <1000 tokens each
  • name
    ：1-64字符，仅小写字母和连字符，需与目录名匹配
  • description
    ：1-1024字符，说明技能的用途与适用场景
  • SKILL.md：令牌数建议不超过500（软限制），绝对不超过5000（硬限制）
  • references/*.md：每个文件令牌数不超过1000

Structure

结构组成

  • SKILL.md
    (required) - Instructions
  • references/
    (optional) - Detailed docs
  • scripts/
    (optional) - Executable code
Frontmatter: 
name
(lowercase-hyphens), 
description
(WHAT + WHEN)
  • SKILL.md
    （必填）- 操作说明
  • references/
    （可选）- 详细文档
  • scripts/
    （可选）- 可执行代码
前置元数据：
name
（小写字母+连字符）、
description
（用途+适用场景）

Progressive Disclosure

渐进式披露

Metadata (~100 tokens) loads at startup. SKILL.md (<5000 tokens) loads on activation. References load only when explicitly linked (not on activation). Keep SKILL.md lean.
元数据（约100令牌）在启动时加载。SKILL.md（最多5000令牌）在技能激活时加载。参考文档仅在显式链接时加载（不会在激活时自动加载）。请保持SKILL.md内容简洁。

Reference Loading

参考文档加载机制

References are JIT (just-in-time) loaded:
  • Only files explicitly linked via 
    [text](references/file.md)
    load
  • Each file loads in full (not sections)
  • No caching between requests - write self-contained files
  • Use recipes/services patterns for multi-option skills
See REFERENCE-LOADING.md for details.
参考文档采用即时（JIT）加载方式：
  • 仅加载通过
    [文本](references/file.md)
    显式链接的文件
  • 每个文件会被完整加载（而非分段加载）
  • 请求之间无缓存 - 请确保文件内容独立完整
  • 多选项技能请使用配方/服务模式
详情请查看REFERENCE-LOADING.md。

Validation

验证方法

bash
undefined
bash
undefined

Run from the scripts directory

Run from the scripts directory

cd scripts npm run tokens -- check plugin/skills/my-skill/SKILL.md
undefined
cd scripts npm run tokens -- check plugin/skills/my-skill/SKILL.md
undefined

Reference Documentation

参考文档

  • GUIDELINES.md - Detailed writing guidelines
  • REFERENCE-LOADING.md - How references load and token efficiency
  • CHECKLIST.md - Pre-submission checklist
  • agentskills.io/specification - Official spec
  • GUIDELINES.md - 详细编写指南
  • REFERENCE-LOADING.md - 参考文档加载机制与令牌效率
  • CHECKLIST.md - 提交前检查清单
  • agentskills.io/specification - 官方规范