# Write A Skill

> 创建具有适当结构、渐进式披露和捆绑资源的新代理技能。当用户想要创建、编写或构建新技能时使用。

- Skill: `karasukaigan/write-a-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add karasukaigan/write-a-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karasukaigan/write-a-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: karasukaigan (https://skillmd.com/u/karasukaigan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karasukaigan/write-a-skill

---


# 编写技能

## 流程

1. **收集需求** - 询问用户：
   - 技能涵盖什么任务/领域？
   - 它应该处理哪些特定用例？
   - 它需要可执行脚本还是仅指令？
   - 有任何参考材料要包括吗？

2. **起草技能** - 创建：
   - 带有简洁指令的 SKILL.md
   - 如果内容超过 500 行，添加额外参考文件
   - 如果需要确定性操作，添加工具脚本

3. **与用户审查** - 展示草稿并询问：
   - 这涵盖你的用例吗？
   - 有什么缺失或不清晰吗？
   - 任何部分应该更详细或更少详细吗？

## 技能结构

```
skill-name/
├── SKILL.md           # 主要指令（必需）
├── REFERENCE.md       # 详细文档（如果需要）
├── EXAMPLES.md        # 使用示例（如果需要）
└── scripts/           # 工具脚本（如果需要）
    └── helper.js
```

## SKILL.md 模板

```md
---
name: skill-name
description: 能力的简要描述。当[特定触发器]时使用。
---

# 技能名称

## 快速开始

[最小工作示例]

## 工作流程

[带有复杂任务清单的逐步流程]

## 高级功能

[链接到单独文件：参见 [REFERENCE.md](REFERENCE.md)]
```

## 描述要求

描述是**你的代理在决定加载哪个技能时看到的唯一东西**。它与所有其他已安装的技能一起在系统提示中显示。你的代理阅读这些描述并根据用户的请求选择相关技能。

**目标**：给你的代理足够的信息以知道：

1. 此技能提供什么能力
2. 何时/为什么触发它（特定关键字、上下文、文件类型）

**格式**：

- 最多 1024 个字符
- 用第三人称书写
- 第一句：它做什么
- 第二句："Use when [特定触发器]"

**好示例**：

```
从 PDF 文件中提取文本和表格，填写表单，合并文档。当处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。
```

**坏示例**：

```
帮助处理文档。
```

坏示例没有给你的代理任何方式来区分这个与其他文档技能。

## 何时添加脚本

当以下情况时添加工具脚本：

- 操作是确定性的（验证、格式化）
- 相同代码会被重复生成
- 错误需要明确处理

脚本节省 token 并提高可靠性相比生成的代码。

## 何时拆分文件

当以下情况时拆分为单独文件：

- SKILL.md 超过 100 行
- 内容有不同领域（金融与销售模式）
- 高级功能很少需要

## 审查清单

起草后，验证：

- [ ] 描述包括触发器（"Use when..."）
- [ ] SKILL.md 少于 100 行
- [ ] 没有时间敏感信息
- [ ] 一致的术语
- [ ] 包括具体示例
- [ ] 引用一层深度