11 KiB

Raw Blame History

技能解剖 - 理解结构

想了解技能在底层如何工作？ 本指南分解了技能文件的每个部分。

📁 基本文件夹结构

skills/
└── my-skill-name/
    ├── SKILL.md              ← 必需：主要技能定义
    ├── examples/             ← 可选：示例文件
    │   ├── example1.js
    │   └── example2.py
    ├── scripts/              ← 可选：辅助脚本
    │   └── helper.sh
    ├── templates/            ← 可选：代码模板
    │   └── template.tsx
    ├── references/           ← 可选：参考文档
    │   └── api-docs.md
    └── README.md             ← 可选：附加文档

**关键规则：**只有 SKILL.md 是必需的。其他一切都是可选的！

SKILL.md 结构

每个 SKILL.md 文件有两个主要部分：

1. 前置元数据（元数据）

2. 内容（指令）

让我们分解每个部分：

第 1 部分：前置元数据

前置元数据在最顶部，用 --- 包裹：

---
name: my-skill-name
description: "简要描述此技能的作用"
risk: safe
source: community
---

必需字段

`name`

**它是什么：**技能的标识符
**格式：**小写-带-连字符
**必须匹配：**文件夹名称完全一致
示例：stripe-integration

`description`

**它是什么：**一句话摘要
**格式：**引号中的字符串
**长度：**保持在 200 字符以内
示例："Stripe 支付集成模式，包括结账、订阅和 Webhook"

`risk`

**它是什么：**技能的安全分类
值：none | safe | critical | offensive | unknown
示例：risk: safe
指南：
- none — 纯文本/推理，无命令或变更
- safe — 读取文件，运行非破坏性命令
- critical — 修改状态，删除文件，推送到生产环境
- offensive — 渗透测试/红队工具；必须包括 "授权使用" 警告
- unknown — 遗留或未分类；新技能优先使用具体级别

`source`

**它是什么：**技能来源的归属
**格式：**URL 或简短标签
示例：source: community、source: "https://example.com/original"
**使用 "self"**如果您是原始作者

可选字段

某些技能包括附加元数据：

---
name: my-skill-name
description: "简要描述"
risk: safe
source: community
author: "your-name-or-handle"
tags: ["react", "typescript", "testing"]
tools: [claude, cursor, gemini]
---

第 2 部分：内容

前置元数据之后是实际的技能内容。这是推荐的结构：

编写有效的指令

使用清晰、直接的语言

❌ 不佳：

您可能想要考虑检查用户是否有身份验证。

✅ 良好：

在继续之前检查用户是否已通过身份验证。

使用动作动词

❌ 不佳：

文件应该被创建...

✅ 良好：

创建文件...

具体明确

❌ 不佳：

正确设置数据库。

✅ 良好：

1. 创建 PostgreSQL 数据库
2. 运行迁移：`npm run migrate`
3. 播种初始数据：`npm run seed`

可选组件

脚本目录

如果您的技能需要辅助脚本：

scripts/
├── setup.sh          ← 设置自动化
├── validate.py       ← 验证工具
└── generate.js       ← 代码生成器

在 SKILL.md 中引用它们：

运行设置脚本：
\`\`\`bash
bash scripts/setup.sh
\`\`\`

示例目录

展示技能的真实示例：

examples/
├── basic-usage.js
├── advanced-pattern.ts
└── full-implementation/
    ├── index.js
    └── config.json

模板目录

可重用的代码模板：

templates/
├── component.tsx
├── test.spec.ts
└── config.json

在 SKILL.md 中引用：

使用此模板作为起点：
\`\`\`typescript
{{#include templates/component.tsx}}
\`\`\`

参考目录

外部文档或 API 参考：

references/
├── api-docs.md
├── best-practices.md
└── troubleshooting.md

技能大小指南

最小可行技能

**前置元数据：**name + description
**内容：**100-200 字
**部分：**概述 + 指令

标准技能

**前置元数据：**name + description
**内容：**300-800 字
**部分：**概述 + 使用时机 + 指令 + 示例

综合技能

**前置元数据：**name + description + 可选字段
**内容：**800-2000 字
**部分：**所有推荐的部分
**额外：**脚本、示例、模板

**经验法则：**从小处开始，根据反馈扩展

格式最佳实践

有效使用 Markdown

代码块

始终指定语言：

\`\`\`javascript
const example = "code";
\`\`\`

列表

使用一致的格式：

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2

强调

粗体用于重要术语：**重要**
斜体用于强调：*强调*
代码用于命令/代码：`代码`

链接

[链接文本](https://example.com)

✅ 质量检查清单

在完成技能之前：

内容质量

指令清晰且可操作
示例现实且有帮助
无拼写错误或语法错误
技术准确性已验证

结构

前置元数据是有效的 YAML
名称与文件夹名称匹配
部分逻辑组织
标题遵循层次结构（H1 → H2 → H3）

完整性

概述解释了"为什么"
指令解释了"如何"
示例展示了"什么"
边缘情况已处理

可用性

初学者可以遵循
专家会发现有用
AI 可以正确解析
解决实际问题

🔍 真实示例分析

让我们分析一个真实技能：brainstorming

---
name: brainstorming
description: "You MUST use this before any creative work..."
---

分析：

✅ 清晰的名称
✅ 强有力的描述和紧迫感（"MUST use"）
✅ 解释何时使用

# Brainstorming Ideas Into Designs

## Overview
Help turn ideas into fully formed designs...

分析：

✅ 清晰的标题
✅ 简洁的概述
✅ 解释价值主张

## The Process

**Understanding the idea:**
- Check out the current project state first
- Ask questions one at a time

分析：

✅ 分解为清晰的阶段
✅ 具体、可操作的步骤
✅ 易于遵循

高级模式

条件逻辑

## 指令

如果用户使用 React：
- 使用函数组件
- 优先使用 hooks 而不是类组件

如果用户使用 Vue：
- 使用组合式 API
- 遵循 Vue 3 模式

渐进式披露

## 基本用法
[常见情况的简单指令]

## 高级用法
[高级用户的复杂模式]

交叉引用

## 相关工作流

1. 首先，使用 `@brainstorming` 进行设计
2. 然后，使用 `@writing-plans` 进行规划
3. 最后，使用 `@test-driven-development` 进行实现

技能有效性指标

如何知道您的技能是否良好：

清晰度测试

不熟悉该主题的人可以遵循吗？
是否有任何模棱两可的指令？

完整性测试

它覆盖了快乐路径吗？
它处理边缘情况吗？
错误场景是否已解决？

有用性测试

它解决了实际问题吗？
您自己会使用它吗？
它节省时间或提高质量吗？

从现有技能学习

研究这些示例

初学者：

skills/brainstorming/SKILL.md - 清晰的结构
skills/git-pushing/SKILL.md - 简单且专注
skills/copywriting/SKILL.md - 良好的示例

高级：

skills/systematic-debugging/SKILL.md - 全面
skills/react-best-practices/SKILL.md - 多个文件
skills/loki-mode/SKILL.md - 复杂工作流

💡 专业提示

从"使用时机"部分开始 - 这阐明了技能的目的
先编写示例 - 它们帮助您理解您在教什么
用 AI 测试 - 在提交之前看看它是否真的有效
获取反馈 - 请其他人审查您的技能
迭代 - 技能根据使用情况随时间改进

要避免的常见错误

❌ 错误 1：太模糊

## 指令
使代码更好。

✅ 修复：

## 指令
1. 将重复逻辑提取到函数中
2. 为边缘情况添加错误处理
3. 为核心功能编写单元测试

❌ 错误 2：太复杂

## 指令
[5000 字密集的技术术语]

✅ 修复： 分解为多个技能或使用渐进式披露

❌ 错误 3：无示例

## 指令
[没有任何代码示例的指令]

✅ 修复： 添加至少 2-3 个真实的示例

❌ 错误 4：过时信息

使用 React 类组件...

✅ 修复： 使用当前最佳实践更新技能

🎯 下一步

阅读 3-5 个现有技能以查看不同的风格
尝试技能模板来自 ../../CONTRIBUTING.md
创建一个简单的技能用于您熟悉的内容
用您的 AI 助手测试它
通过拉取请求分享

**记住：**每个专家都曾经是初学者。从简单开始，从反馈中学习，并随时间改进！🚀

11 KiB Raw Blame History Unescape Escape

技能解剖 - 理解结构

📁 基本文件夹结构

SKILL.md 结构

1. 前置元数据（元数据）

2. 内容（指令）

第 1 部分：前置元数据

必需字段

name

description

risk

source

可选字段

第 2 部分：内容

推荐的部分

1. 标题（H1）

2. 概述

3. 使用时机

4. 核心指令

5. 示例

6. 最佳实践

7. 常见陷阱

8. 安全与安全说明（针对命令/网络/攻击性技能）

9. 相关技能

编写有效的指令

使用清晰、直接的语言

使用动作动词

具体明确

可选组件

脚本目录

示例目录

模板目录

参考目录

技能大小指南

最小可行技能

标准技能

综合技能

格式最佳实践

有效使用 Markdown

代码块

列表

强调

链接

✅ 质量检查清单

内容质量

结构

完整性

可用性

🔍 真实示例分析

高级模式

条件逻辑

渐进式披露

交叉引用

技能有效性指标

清晰度测试

完整性测试

有用性测试

从现有技能学习

研究这些示例

💡 专业提示

要避免的常见错误

❌ 错误 1：太模糊

❌ 错误 2：太复杂

❌ 错误 3：无示例

❌ 错误 4：过时信息

🎯 下一步

11 KiB

Raw Blame History

`name`

`description`

`risk`

`source`