企业官网建设流程全解析

• AI 技能
• AI 插件

导读

本文是 agentic-awesome-skills（AAS）仓库的贡献实战指南。仓库本身是一个面向 Agent 的技能集合生态，内置了 2,400+ 个 agentic skills，并配套 CLI、本地 MCP、目录索引与插件体系（见 package.json）。无论你是第一次参与开源的新手，还是想把自己的专业经验封装成SKILL.md的开发者，读完本文你都能掌握：完整的贡献流程、标准化的 Skill 元数据（frontmatter）规范、本地校验命令（npm run validate等）、安全敏感内容的审查红线，以及提交 PR 时哪些文件绝不能提交。全文以 CONTRIBUTING.md 为主体骨架，并引入仓库源码与测试验证其真实机制。

一、快速开始：5 步提交你的第一个 Skill

仓库官方推荐的最小贡献路径非常直接，全部命令如下：

# 1. Fork and clone git clone https://github.com/YOUR-USERNAME/agentic-awesome-skills.git cd agentic-awesome-skills # 2. Install dependencies npm install # 3. Create your skill mkdir -p skills/my-awesome-skill # 4. Use the canonical template cp docs/contributors/skill-template.md skills/my-awesome-skill/SKILL.md # 5. Edit and validate npm run validate # For SKILL.md with shell/network/credential/mutation guidance: npm run security:docs # 6. Open a PR git add skills/my-awesome-skill/ git commit -m "feat: add my-awesome-skill for [purpose]" git push origin my-branch

打开 PR 时使用仓库默认模板（见 .github/PULL_REQUEST_TEMPLATE.md），并开启Allow edits from maintainers，这样维护者可以直接在分支上解决冲突，减少来回沟通成本。如果 PR 新增或修改了SKILL.md，GitHub 会自动在 PR 上运行skill-review自动化工作流。

需要特别强调的原则：社区 PR 应保持 source-only，即只提交源文件，不要把生成的注册表产物（如CATALOG.md、skills_index.json、data/*.json）包含进 diff。这些产物会在合并到main后由仓库统一规范化生成。

自动化校验是必要的，但它不能替代人工逻辑审查。如果 PR 新增或修改了 Skill，或引入了命令、网络、凭证、变更（mutation）、安装或安全类指导，即使所有自动化检查都通过，也必须人工复核其逻辑与失败模式。如果只想改进文档，直接在 GitHub 网页上编辑同样完全可行。

二、贡献的四种方式

不需要是专家也能参与，官方列出了四种人人可做的贡献途径：

1. 改进文档（最轻松）：修正拼写或语法、让解释更清晰、为现有 Skill 补充示例、把文档翻译成其他语言。仓库本身就有完整的docs_zh-CN/中文文档目录，翻译类贡献是真实存在的需求。
2. 报告 Issue：发现可复现的 bug 就开 Issue；需要帮助、想反馈或想法还处于早期阶段，先在 Discussion 里讨论；Skill 不工作且能复现则开 Issue，不确定就走 Q&A。
3. 创建新 Skill：把专业经验封装成 Skill、填补当前技能集合的空白、或改进现有 Skill。
4. 测试与验证：实际试用各类 Skill 并反馈可用性、在不同的 AI 工具上测试、提出改进建议。

三、如何改进文档

3.1 零 Git 知识方案（超级简单）

1. 在 GitHub 上找到要改进的文件；
2. 点击铅笔图标（✏️）进入编辑；
3. 在浏览器里直接修改；
4. 点击 "Propose changes"；
5. 完成！维护者会审查并合并。

3.2 使用 Git 的标准流程

# 1. Fork the repo on GitHub（点击 Fork 按钮） # 2. Clone your fork git clone https://github.com/YOUR-USERNAME/agentic-awesome-skills.git cd agentic-awesome-skills # 3. Create a branch git checkout -b improve-docs # 4. Make your changes（用你喜欢的编辑器修改文件） # 5. Commit and push git add . git commit -m "docs: make XYZ clearer" git push origin improve-docs # 6. Open a Pull Request on GitHub

四、如何创建一个新 Skill

4.1 什么样的 Skill 是好 Skill

一个合格的 Skill 应该：

• ✅ 解决一个具体问题
• ✅ 可跨项目复用
• ✅ 有清晰的操作说明
• ✅ 尽可能包含示例

4.2 六步创建你的第一个 Skill

Step 1：选题。问自己三个问题：我擅长什么？我希望 AI 助手更懂什么？我反复在做哪些任务？官方给出的示例："我擅长 Docker，那就创建一个 Docker skill"；"我希望 AI 更懂 Tailwind"；"我总在搭同一套测试模式"。

Step 2：创建目录结构。Skill 目录统一放在skills/下，目录名使用小写加连字符（kebab-case）：

cd skills/ mkdir my-awesome-skill cd my-awesome-skill touch SKILL.md

Step 3：编写 SKILL.md。每个 Skill 都必须从规范模板 docs/contributors/skill-template.md 起步。贡献者基线 frontmatter 如下：

--- name: my-awesome-skill description: "Brief one-line description of what this skill does" category: development risk: safe source: community source_repo: owner/repo source_type: community date_added: "2026-03-06" author: your-name-or-handle tags: [tag-one, tag-two] tools: [claude, cursor, gemini] ---

frontmatter 字段语义与校验规则（以下规则在 tools/scripts/validate_skills.py 中有硬性实现）：

• name：必须与所在目录名完全一致，否则校验直接报错（Name does not match folder name）。
• description：一句话描述 Skill 的功能与使用场景，必须是非空字符串，长度上限 300 字符（源码中len(desc) > 300即报错），推荐控制在 200 字符内。
• risk：合法取值只有none、safe、critical、offensive、unknown五种。缺省会被当作 warning 并默认视为unknown；非法取值直接报错。unknown仅适用于真正遗留或尚未分类的内容。
• source/source_repo/source_type：如果 Skill 改编自外部 GitHub 仓库，必须同时声明source_repo: owner/repo和source_type: official或source_type: community；如果是仓库原创内容，用source: self和source_type: self。校验器要求source_repo必须匹配OWNER/REPO格式，source_type只能是official、community、self三者之一。
• date_added：可选但推荐，必须符合YYYY-MM-DD格式，否则报错。
• tools：声明 Skill 面向的 AI 工具，如[claude, cursor, gemini]。

正文部分的标准结构（模板完整内容见 docs/contributors/skill-template.md）：

# Skill Title ## Overview Explain what this skill does and when to use it. （如改编自外部仓库，需声明 source_repo 与 source_type；原创内容用 source: self / source_type: self） ## When to Use This Skill - Use when [scenario 1] - Use when [scenario 2] - Use when [scenario 3] ## How It Works ### Step 1: [First Step] ### Step 2: [Second Step] ### Step 3: [Final Step] ## Examples ### Example 1: [Common Use Case] ### Example 2: [Another Use Case] ## Best Practices - ✅ Do this - ❌ Don't do this ## Common Pitfalls - **Problem:** Description **Solution:** How to fix it ## Additional Resources

注意两点校验细节：## When to Use章节是触发条件（trigger）校验项，缺失会产生 warning（严格模式下升级为 error），源码中的WHEN_TO_USE_PATTERNS正则兼容多种写法（如 "When to Use"、"Use this skill when" 等）；另外，SKILL.md 中的 Markdown 相对链接会被逐个检查是否存在（dangling link 检测），所以正文里引用的本地文件路径必须是真实存在的。

Step 4：测试你的 Skill。把它复制到所用 AI 工具的 skills 目录：

cp -r skills/my-awesome-skill ~/.agents/skills/

或者复制到具体工具的路径，例如~/.claude/skills/、~/.cursor/skills/，或自定义工作区路径如.agent/skills/。然后实际调用验证：

@my-awesome-skill help me with [task]

能用？很好！不行就继续打磨。

Step 5：校验你的 Skill。不同变更类型的校验路径不同：

纯 Skill PR：

npm install npm run validate

文档 / 工作流 / 基础设施变更：

npm install npm run validate npm run validate:references npm test

可选的管理员级预检：

npm run pr:preflight

Python-only 回退方案：

python3 tools/scripts/validate_skills.py

npm run validate实际执行的是node tools/scripts/run-python.js tools/scripts/validate_skills.py（见 package.json），校验器会检查：✅ SKILL.md 存在；✅ frontmatter 正确；✅ name 与目录名一致；✅ description 存在；✅ 引用数据与文档 bundle 保持一致。--strict模式（对应npm run validate:strict）会把所有 warning 升级为 error，适合较大的清理型 PR，但仓库里仍存在不满足严格质量标准的遗留 Skill。

重要提醒：通过npm run validate或skill-review不代表 Skill 变更可以免审。提交 PR 前必须人工复核：触发条件的清晰度（Skill 是否会在正确的场景被触发）、说明与示例的正确性、明显的失败模式与不安全假设、以及用户可见的边界情况，最后确认声明的risk:级别与实际行为仍然匹配。

禁止提交的生成产物。普通 PR 不要提交以下文件，它们会在合并到main后由仓库规范化生成：

• CATALOG.md
• skills_index.json
• data/skills_index.json
• data/catalog.json
• data/bundles.json
• data/aliases.json

Step 6：提交你的 Skill：

git add skills/my-awesome-skill/ git commit -m "feat: add my-awesome-skill for [purpose]" git push origin my-branch # 然后在 GitHub 上打开 Pull Request

五、安全敏感内容的专项审查

如果 Skill 中包含以下任何一类内容，需要额外做一轮安全预检：

• shell 命令或命令式示例（curl、wget、bash、powershell、irm等）；
• 网络指令或凭证/令牌示例；
• 直接的文件系统、进程或变更（mutation）指导。

执行：

npm run security:docs npm test

npm run security:docs对应 tools/scripts/tests/docs_security_content.test.js，它会扫描仓库中真实存在的 Skill 内容（如skills/apify-actorization/SKILL.md、skills/audio-transcriber/examples/basic-transcription.sh等）与 CI 工作流，检查是否存在被阻止的高危示例。

预期结果：✅ 除非有正当理由，否则没有被阻止的高危示例；✅ 对任何刻意保留的高危文档命令模式，必须添加显式 allowlist 注释（<!-- security-allowlist: ... -->）；✅ 如果示例刻意包含风险，且预期用途需要本地管理员权限或托管环境，必须在 PR 描述中明确说明。

对于具备攻击性或破坏能力的 Skill，还需要验证：

• risk:设置为offensive或critical（按实际情况）；
• 操作说明中明确写有用户确认与授权前置条件；
• 相关 Skill 中包含标准的 "Authorized Use Only" 免责声明。

这些红线在源码中有硬性约束：校验器会检查risk: offensive的 Skill 是否包含精确匹配的授权使用免责声明，以及 "Mandatory confirmation gate"（强制确认门槛，要求精确目标 URL/IP/账号/资源并在当前对话中等待显式确认）——缺失即报错（见 tools/scripts/validate_skills.py）。对应的测试位于 tools/scripts/tests/test_offensive_skill_guardrails.py。

可选的加固检查：

npm run validate:strict

validate:strict适合较大的清理型 PR 前使用，但仓库中仍存在未完全满足严格质量标准的遗留 Skill。

六、提交 PR 的完整 Checklist

提交贡献前逐项确认：

• Skill 有清晰、描述性的名称
• SKILL.md从规范模板起步，包含完整 frontmatter（name、description、category、risk、source、date_added）
• 改编自外部 GitHub 仓库的 Skill 声明了source_repo与source_type；原创内容使用source: self和source_type: self
• 已包含示例
• 已用 AI 助手实际测试过 Skill
• 已运行npm run validate
• 如果修改了SKILL.md或风险性指导，已人工复核逻辑、安全性与可能失败模式，而非仅依赖自动化检查
• 变更涉及文档、工作流或基础设施时，已运行npm run validate:references和npm test
• Skill 含命令、网络访问、凭证或破坏性指导时，已运行文档安全扫描（npm run security:docs）
• 未在 PR 中包含生成产物（CATALOG.md、skills_index.json、data/*.json）
• commit message 清晰（如 "feat: add docker-compose skill"）
• 在 PR 上开启了Allow edits from maintainers
• 已检查拼写与语法

仓库的 PR 模板（.github/PULL_REQUEST_TEMPLATE.md）同样要求勾选质量栏，包括：已阅读 docs/contributors/quality-bar.md 与 docs/contributors/security-guardrails.md、risk:标签正确、包含## Limitations章节、offensive Skill 带免责声明、检查了skill-review工作流结果、以及外部source_repo的许可证来源声明（license:与license_source:）等。

七、Commit Message 规范

使用以下前缀：

• feat:- 新 Skill 或重大特性
• docs:- 文档改进
• fix:- 缺陷修复
• refactor:- 不改变功能的重构
• test:- 新增或更新测试
• chore:- 维护任务

示例：

feat: add kubernetes-deployment skill docs: improve getting started guide fix: correct typo in stripe-integration skill docs: add examples to react-best-practices

八、报告 Issue 的正确姿势

发现 Bug：

1. 先检查已有 Issue，可能已经有人报过了；
2. 开新 Issue 时提供：哪个 Skill 出了问题？用的什么 AI 工具？期望发生什么？实际发生了什么？复现步骤？

发现文档令人困惑：

1. 开一个标题为 "Documentation unclear: [topic]" 的 Issue；
2. 说明：哪部分令人困惑？期望找到什么？怎样写才能更清晰？

九、贡献者认可与代码规范

所有贡献者都会在 Contributors 页面获得认可。项目始终通过 GitHub 以 "Squash and merge" 方式合并，因此你的 PR 会显示为 Merged 并获得完整署名；不会出现本地整合后关闭 PR 的情况。如果 PR 有合并冲突，维护者会在分支上解决（或要求你先合并 main 再推送），以确保最终在 GitHub 上完成合并。

社区行为规范强调：互相尊重与包容、欢迎新人、建设性反馈、帮助他人学习。

十、进一步学习

文档改进类贡献可以进一步参考：docs/contributors/quality-bar.md（质量门槛）、docs/contributors/security-guardrails.md（安全护栏）、docs/contributors/skill-anatomy.md（Skill 解剖）、docs/contributors/examples.md（示例）以及 docs/contributors/community-guidelines.md（社区准则）。Skill 主题选择与目录生态可以参考 CATALOG.md 与 skills/ 目录下已有的 2,400+ 个 Skill 作为灵感。

结语

无论你的贡献是修正一个拼写、改进一个句子，还是创建一整个全新 Skill，都能让这个项目变得更好。从复制 docs/contributors/skill-template.md 模板开始，写好 frontmatter，跑通npm run validate，注意安全扫描红线，提交 source-only 的 PR——你就已经完整走通了 agentic-awesome-skills 的贡献流程。

• AI 技能
• AI 插件