skill-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Follow these steps to generate a skill that adheres to the agentskills.io specification and progressive disclosure principles.

按照以下步骤生成符合agentskills.io规范和渐进式披露原则的技能。

Define a unique
```
name
```
: 1-64 characters, lowercase, numbers, and single hyphens only.
Draft a
```
description
```
: Max 1,024 characters, written in the third person, including negative triggers.
Execute Validation Script: Run the validation script to ensure compliance before proceeding:
```
python3 scripts/validate-metadata.py --name "[name]" --description "[description]"
```
If the script returns an error, self-correct the metadata based on the
```
stderr
```
output and re-run until successful.

执行验证脚本：在继续之前运行验证脚本以确保合规：

python3 scripts/validate-metadata.py --name "[name]" --description "[description]"

Use the template in
```
assets/skill-template.md
```
as the starting point.
Write all instructions in the third-person imperative (e.g., "Extract the text," "Run the build").
Enforce Progressive Disclosure:
- Keep the main logic under 500 lines.
- If a procedure requires a large schema or complex rule set, move it to
```
references/
```
  .
- Command the agent to read the specific file only when needed: "Read references/api-spec.md to identify the correct endpoint."

Identify "fragile" tasks (regex, complex parsing, or repetitive boilerplate).
Outline a single-purpose script for the
```
scripts/
```
directory.
Ensure the script uses standard output (stdout/stderr) to communicate success or failure to the agent.

Review the
```
SKILL.md
```
for "hallucination gaps" (points where the agent is forced to guess).
Verify all file paths are relative and use forward slashes (
```
/
```
).
Cross-reference the final output against
```
references/checklist.md
```
.

Metadata Failure: If
```
scripts/validate-metadata.py
```
fails, identify the specific error (e.g., "STYLE ERROR") and rewrite the field to remove first/second person pronouns.
Context Bloat: If the draft exceeds 500 lines, extract the largest procedural block and move it to a file in
```
references/
```
.

元数据验证失败：如果
```
scripts/validate-metadata.py
```
执行失败，识别具体错误类型（例如："STYLE ERROR"），重写字段以移除第一/第二人称代词。
上下文内容冗余：如果草稿超过500行，将最大的流程块提取并移至
```
references/
```
目录下的文件中。