用途
tkr-skill-writer 是一个面向技能作者的指南型技能，用于在创建或更新技能时提供结构规范、模板和最佳实践。它的目标是让仓库内的技能保持一致的格式、清晰的文档和规范的引用组织，同时与当前 Codex 技能指南保持一致。
主要能力
- 规定技能必须满足的官方最小格式：一个包含 SKILL.md 的技能文件夹，前置元数据包含 name 和 description，以及明确说明技能何时触发的指令。
- 推荐本仓库偏好的三段式结构：Description and Goals（描述与目标）、What This Skill Should Do（该技能应做什么）、Information About the Skill（关于技能的信息，含子分类）。
- 指导引用文件的组织：引用文件应位于 SKILL.md 下一层（如 references/filename.md），使用从技能根目录出发的相对路径，避免深层嵌套的引用链。
- 指导以表格形式组织组件/系统引用，组件名作为可点击链接，并附“When to Use”说明。
- 说明可选元数据的添加方式：在 agents/openai.yaml 中设置界面显示名称、简短描述、图标、品牌色和默认提示词，以及策略和依赖。
- 提供统一的格式规范：使用 markdown 链接引用文件、保持表格可读、提供清晰可操作的描述。
使用方式
当创建或更新技能时，该技能会引导你：
- 从官方最小格式开始：技能文件夹 + SKILL.md + name/description 前置元数据 + 明确触发条件的指令。
- 应用本仓库偏好的三段式结构。
- 创建一层深度的引用文件，使用相对路径，避免嵌套引用链。
- 用表格组织组件/系统引用，组件名作为可点击链接，并写明何时加载每个引用。
- 在有用时添加可选元数据，例如在 agents/openai.yaml 中配置界面元数据；仅在技能确实需要时添加 policy 或 dependencies。
- 遵循一致的格式：markdown 链接、可读表格、清晰可操作的描述。
技能结构模板如下：
skill-name/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── assets/
│ └── logo.svg
└── references/
└── reference.md
SKILL.md 前置元数据示例：
---
name: skill-name
description: Brief description of what the skill does and when to use it.
---
可选元数据示例（agents/openai.yaml）：
interface:
display_name: "Optional user-facing name"
short_description: "Optional user-facing description"
icon_small: "../assets/small-logo.svg"
icon_large: "../assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Optional surrounding prompt to use the skill with"
policy:
allow_implicit_invocation: false
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs"
description: "OpenAI Docs MCP server"
transport: "streamable_http"
url: "https://developers.openai.com/mcp"
引用表格格式：
| Component | When to Use |
|-----------|-------------|
| [`ComponentName`](references/componentname.md) | Clear description of when to use this component. |
引用文件命名约定：组件文件使用 {name}component.md（如 modelcomponent.md）；系统文件使用 system.md（将所有系统信息合并到一个文件）；其他引用使用描述性的小写连字符命名。
适用场景
- 在 Codex 技能体系中新建技能。
- 更新或维护已有技能，使其符合仓库统一风格。
- 需要让技能更易被发现、更易导航，并为每个技能提供清晰的“何时使用”指引。
- 需要统一引用文件组织方式，并区分仓库约定与 Codex 实际要求。
限制
- 该技能是指南型技能，提供的是结构与格式规范，不包含具体业务功能的实现。
- policy 和 dependencies 仅在确实需要时添加，不应默认添加。
- 仓库特定的布局规则属于约定，而非 Codex 本身强制的要求。
- 资料未提供该技能的收费、价格、平台支持范围或效果数据。