Skill Authoring Guide / 技能编写指南

Use this reference when the task needs detail beyond the main workflow in SKILL.md.

当任务需要超出 SKILL.md 主工作流的细节时，使用本参考。

Naming / 命名

• Directory name: kebab-case
  目录名：kebab-case
• Frontmatter name: snake_case
  front matter 的 name：snake_case
• Keep names short, concrete, and capability-based
  名称要简短、具体、基于能力
• Namespace by provider or domain when it improves trigger clarity, for example google-calendar or outlook-calendar
  当按提供方或领域加命名空间能提升触发清晰度时就这么做，例如 google-calendar 或 outlook-calendar

Resource Split / 资源拆分

Choose the smallest structure that carries the skill reliably.

选择能可靠承载该技能的最小结构。

• Keep instructions in SKILL.md when they are short, stable, and required on every trigger.
  当指令简短、稳定且每次触发都需要时，保留在 SKILL.md 中。
• Use references/ when the detail is useful but conditional: long examples, schemas, variant-specific notes, or extended workflows.
  当细节有用但属条件性内容（长示例、模式、特定变体的说明或扩展工作流）时，放入 references/。
• Use assets/ only for files that become part of the delivered output.
  assets/ 只用于会成为交付输出一部分的文件。
• For Jarvis bundled skills, prefer bin/ helpers for repeated protocol, credential, or parsing work. Do not leave those mechanics in prompt text if a helper can own them.
  对于 Jarvis 内置技能，重复的协议、凭据或解析工作优先交给 bin/ 辅助脚本完成。如果辅助脚本能承担，就不要把这些机制留在提示词文本里。

Frontmatter Template / Front matter 模板

---
name: "my_skill"
description: "One-line description of what the skill does and when to use it."
---

Notes:

说明：

• name and description are the core trigger surface.
  name 和 description 是核心触发面。
• Bundled skills should usually not set metadata.includeInPrompt.
  内置技能通常不应设置 metadata.includeInPrompt。

Body Templates / 正文模板

Tool-backed skill / 基于工具的技能

# Skill Title

## Purpose
One line.

## Tooling
Exact commands, key flags, and the response fields the model should parse.

## Auth
Where auth lives, what setup to do first, and what not to print.

## Operating Rules
Short numbered constraints the tool itself does not enforce.

Workflow-only skill / 纯工作流技能

# Skill Title

## Purpose
One line.

## Workflow
Ordered steps for the agent.

## Output Contract
What the final result should contain.

## Operating Rules
Short numbered constraints.

What to Move Out of SKILL.md / 应从 SKILL.md 移出的内容

• Long API endpoint catalogs
  冗长的 API 端点目录
• Full response schema dumps
  完整的响应模式转储
• Repeated auth/token extraction snippets
  反复出现的认证/令牌提取片段
• Lengthy tutorials or background essays
  冗长的教程或背景长文
• Large blocks of variant-specific guidance that only apply sometimes
  只在部分情况适用的大段特定变体指导

Move that material to references/ and link it from the relevant section in SKILL.md.

把这些材料移到 references/，并从 SKILL.md 的相关章节链接过去。

Review Checklist / 检查清单

• Does the description clearly state both capability and trigger context?
  description 是否同时清楚说明了能力与触发场景？
• Is the skill scoped to one coherent job?
  技能是否限定于一个连贯的职责？
• Does SKILL.md tell the model what to do next, instead of teaching the whole subject?
  SKILL.md 是在告诉模型下一步做什么，而不是讲授整个主题？
• Are commands and paths real for this repo/runtime?
  命令与路径在本仓库/运行时中是否真实存在？
• Are auth expectations explicit when needed?
  需要时认证预期是否写明确切？
• Did you remove includeInPrompt unless there is a strong reason to keep it?
  除非有充分理由保留，你是否已移除 includeInPrompt？
• If the skill uses helpers, does the prompt rely on them instead of duplicating their work?
  如果技能使用辅助脚本，提示词是否依赖它们而不是重复其工作？