Back to Details

skill-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Authoring Best Practices

Skill编写最佳实践

Use this skill when you need to create or refactor a pi skill. Keep it short and defer to the canonical reference for full rules and examples.
当你需要创建或重构Pi Skill时，请遵循本Skill的指引。内容力求简洁，完整规则与示例请参考标准参考文档。

Canonical Reference

标准参考文档

Follow the full specification and patterns here:
  • agent/skills/pi/references/skills.md
Only repeat details in this file when they are essential to the current task.
请遵循以下完整规范与模式：
  • agent/skills/pi/references/skills.md
仅在当前任务必需时，才在此文件中重复相关细节。

Authoring Workflow (Condensed)

编写流程（精简版）

  1. Clarify scope: Identify what the skill should do and the trigger phrases that should load it.
  2. Plan resources: Decide which logic belongs in scripts, references, or assets instead of SKILL.md.
  3. Write the skill: Add frontmatter, concise instructions, and links to references (one level deep).
  4. Validate and iterate: Use the skill on real tasks, note friction, and tighten wording.
  1. 明确范围：确定Skill应实现的功能以及触发加载该Skill的短语。
  2. 规划资源：决定哪些逻辑应放在脚本、参考文档或资源文件中，而非SKILL.md内。
  3. 编写Skill：添加前置元数据、简洁说明，并链接至参考文档（仅一级深度）。
  4. 验证与迭代：在实际任务中使用该Skill，记录使用痛点，优化表述。

Content Placement Heuristics

内容放置原则

  • SKILL.md: Overview, decision points, and minimal instructions.
  • references/: Deep guides, specs, or domain docs the agent should read on demand.
  • scripts/: Deterministic code you don’t want rewritten every time.
  • assets/: Files used in outputs (templates, logos, etc.).
  • SKILL.md：概述、决策要点及极简操作说明。
  • references/：Agent按需查阅的深度指南、规范或领域文档。
  • scripts/：无需每次重写的确定性代码。
  • assets/：输出中使用的文件（如模板、logo等）。

Red Flags

注意事项（红色预警）

  • Duplicate information between SKILL.md and references.
  • Long explanations of obvious concepts.
  • Extra docs (README, changelog) that won’t be used by the agent.
  • SKILL.md与参考文档之间存在重复信息。
  • 对显而易见的概念进行冗长解释。
  • 添加了Agent不会使用的额外文档（如README、变更日志）。