DevOps-Security-Agent-Skills 是一个面向 AI Agent 的 DevOps、安全与合规知识库，收录了 80+ 个技能，而每个技能的核心就是一个 SKILL.md 文件。本文将从零讲清如何编写 SKILL.md：包含完整模板、命名规范与 PR 提交流程，助你向这个项目贡献自己的第一个技能。

📌 为什么要编写 SKILL.md？

Agent Skills 是一种扩展 AI Agent 的开放格式。每个技能本质上是一个文件夹，工作流程分为三步：

1. DISCOVER：Agent 启动时扫描所有技能目录
2. MATCH：根据 SKILL.md 前置元数据（frontmatter）中的name和description匹配用户提问
3. ACTIVATE：命中后加载完整 SKILL.md，并按需执行 scripts/ 中的脚本

所以，写一份高质量的 SKILL.md，就是给 Claude Code、Cursor、Codex 等 Agent 装上"能直接执行的专业知识"。想快速建立标准印象，可以阅读 devops/orchestration/kubernetes-ops/SKILL.md，它完整展示了"When to Use、Prerequisites、配置示例、Common Issues、Best Practices、Related Skills"这些章节。

第 1 步：理解技能的目录结构

每个技能是一个独立目录，最少只需一个 SKILL.md：

skill-name/ ├── SKILL.md # 必需：说明 + 元数据 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：详细文档 └── assets/ # 可选：模板、配置

各可选目录的使用时机：

例如 security/hardening/linux-hardening/ 技能把加固配置模板放在 assets/ 下（如 ssh-hardening.conf），CIS 检查清单放在 references/ 下。

第 2 步：填写 SKILL.md 模板 📝

官方模板原文见 CONTRIBUTING.md。SKILL.md 由两部分组成：

YAML Frontmatter（元数据头部）

--- name: skill-name description: 说明这个技能做什么、什么时候使用。要包含能帮助 Agent 识别任务的具体关键词。 license: MIT metadata: author: your-username version: "1.0" ---

其中description 是 Agent 匹配的关键字段，三条写作要点：

• 长度 1~1024 字符
• 既要说明"做什么"，也要说明"何时用"
• 包含具体的匹配关键词

对比感受一下差别：

❌ 差：Helps with Docker.

✅ 好：Deploy and manage Docker containers including building images, optimizing Dockerfiles, managing volumes, and troubleshooting container issues. Use when working with Docker, containers, or containerization.

正文标准章节

写作时记得：解释"为什么"而不只是"怎么做"；示例命令提交前必须亲自测试过；命令加注释，关键处附上预期输出。

第 3 步：遵循技能命名规范 ⚠️

这是最容易被打回的环节，共 5 条硬性规则：

1. 只允许小写字母、数字、连字符
2. 最长64 个字符
3. 不能以连字符开头或结尾
4. 不能出现连续连字符
5. 目录名必须与 frontmatter 中的name字段完全一致

✅ 好例子：github-actions、terraform-aws、linux-hardening❌ 坏例子：GitHub-Actions（大写）、-github-actions（开头连字符）、github--actions（连续连字符）

文件命名也有约定：

• Markdown 文档：小写 + 连字符，如pipeline-syntax.md
• 脚本文件：小写 + 下划线，如cluster-health-check.sh

第 4 步：选对领域目录放置技能

项目按领域组织，新技能要放进正确的领域和分类下：

不确定放哪里时，先浏览 README.md 的技能目录，找到主题最接近的已有技能，放进同一分类即可。

第 5 步：PR 前的清单与提交流程 🚀

提交前 5 项自查

• 校验技能：在本地运行skills-ref validate ./path/to/your-skill
• 测试指令：确保每条命令都能按文档执行成功
• 检查重复：确认仓库中不存在类似技能
• 风格一致：对照现有技能（如 security/scanning/vulnerability-scanning/SKILL.md）核对风格
• 控制篇幅：主 SKILL.md 保持在500 行以内，超出部分移到 references/

渐进式披露原则

为高效利用 Agent 的上下文，技能内容应分层组织：

1. Frontmatter（约 100 tokens）：只有 name 和 description
2. 主指令（<5000 tokens）：SKILL.md 核心内容
3. References（按需加载）：详细文档放在独立文件中

PR 提交流程

# 1. 在平台 Fork 项目后，克隆你的 fork git clone https://gitcode.com/gh_mirrors/de/DevOps-Security-Agent-Skills # 2. 新建分支 → 添加技能 → 提交 Pull Request

PR 描述建议包含：清晰描述性的标题、关联 issue、技能做什么及为何有价值、你做过哪些测试。

维护者会从 5 个维度评审：Accuracy（准确）、Clarity（清晰）、Completeness（完整）、Consistency（一致）、Value（价值）。对贡献有疑问或想提新技能想法，直接开一个 Issue 讨论即可。

🎯 总结

按这 5 步走，你的第一个技能就能顺利合入。参考 CONTRIBUTING.md 中的完整规范，开始你的贡献之旅吧！