mcpField
S
skill-writing-best-practices

skill-writing-best-practices

github.com/sergiodxaAgent 工作流92173 次安装38 周前更新
代码仓库

关于 skill-writing-best-practices

这是一份编写 AI Agent 技能的指南，帮助记录编码规范。六条规则涵盖文件结构、具体示例、解释原因和自然表达，适用于创建或审查技能。

主要功能

  1. 01六条技能编写规则
  2. 02技能及规则文件结构
  3. 03提供具体代码示例
  4. 04说明规则背后的原因
  5. 05自然的写作风格

适用场景

  1. 01起草新技能
  2. 02从代码库提取规范
  3. 03审查或改进技能
  4. 04将文档转为技能

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sergiodxa/agent-skills --skill skill-writing-best-practices

安装后在 Claude Code 中输入/skill-writing-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

rules/
concrete-examples.md
explain-why.md
rule-file-structure.md
skill-directory-structure.md
skill-md-structure.md
writing-style.md

详细介绍

技能编写最佳实践

用于创建高效 AI Agent 技能的模式，帮助总结编码规范和最佳实践。包含 6 条规则，涵盖结构、内容和写作风格。

适用场景

在以下情况下参考这些指南：

  • 从头开始创建新技能
  • 从现有代码库中提取模式
  • 审查或改进现有技能
  • 将文档转换为技能格式

规则摘要

结构（高）
skill-directory-structure - @rules/skill-directory-structure.md

每个技能都包含一个 SKILL.md 和一个 rules/ 目录。

skills/
└── topic-best-practices/
    ├── SKILL.md              # Main summary with all rules
    └── rules/
        ├── rule-name.md      # Detailed individual rules
        └── another-rule.md
skill-md-structure - @rules/skill-md-structure.md

SKILL.md 包含前置元数据、概述和精简的规则摘要。

---
name: topic-best-practices
description: When to use this skill.
---

# Topic Best Practices

Brief intro. Contains N rules across M categories.

## When to Apply

- Situation 1
- Situation 2

## Rules Summary

### Category (IMPACT)

#### rule-name - @rules/rule-name.md

One sentence. Code example.
rule-file-structure - @rules/rule-file-structure.md

每个规则文件都包含前置元数据、说明、示例和要点总结。

---
title: Rule Title
impact: HIGH
tags: [relevant, tags]
---

# Rule Title

What to do and why.

## Why

- Benefit 1
- Benefit 2

## Pattern

\`\`\`ruby
# Bad
bad_code

# Good
good_code
\`\`\`

## Rules

1. Takeaway 1
2. Takeaway 2
内容（高）
concrete-examples - @rules/concrete-examples.md

每条规则都需要代码示例。抽象的建议很难应用。

# Bad: Too abstract
"Keep your code organized."

# Good: Concrete
"Place concerns in `app/models/model_name/` not `app/models/concerns/`."

\`\`\`ruby
# Shows exactly what to do
app/models/card/closeable.rb
\`\`\`
explain-why - @rules/explain-why.md

不要只展示做法，还要解释其重要性。

## Why

- **Testability**: Sync method can be tested without job infrastructure
- **Flexibility**: Callers choose sync or async based on context
- **Clarity**: The `_later` suffix makes async behavior explicit
风格（中）
writing-style - @rules/writing-style.md

自然地写作。避免 AI 腔和过度格式化。

# Bad
---
Here is an overview of the key points:
---

# Good
Group related rules by category. Each rule gets a one-sentence
description and a short code example.

理念

优秀的技能应当：

  1. 具体 - 每条规则都有代码示例
  2. 有理有据 - 解释原因，而不只是说明做法
  3. 便于浏览 - 能快速找到相关规则
  4. 坦诚 - 说明何时不应使用某种模式
  5. 自然 - 写得像文档，而不是 AI 输出

评论

支持 Markdown