如何给full-stack-skills贡献技能:从零编写并上架你的第一个Agent Skills
如何给full-stack-skills贡献技能:从零编写并上架你的第一个Agent Skills
full-stack-skills 是一个免费的全栈开发技能市场,聚合了 51 个技能包、788 个 Agent Skills,覆盖前端、后端、移动端、DevOps 与 AI 设计工具。想把自己的领域经验变成可复用的 AI 技能?本文用 4 个步骤带你完成从零编写 SKILL.md 到提交 PR 上架的完整流程,新手也能快速上手。
为什么选择向 full-stack-skills 贡献技能
- 受众广:技能可被 Claude Code、Codex、Cursor 等主流 AI 编码智能体加载,一次编写、多平台复用
- 标准化:遵循 Agent Skills 规范,技能以独立目录发布,可跨项目安装
- 有回报:你的技能会被收录进 技能索引,供全社区一键安装
动手前:先搞懂 Agent Skills 的核心规范
一个技能本质上就是一个带 SKILL.md 的目录。编写前先通读两份权威文档:
- spec/agent-skills-spec.md:规范摘要(目录结构、frontmatter 约束、渐进式披露机制)
- docs/AGENT_SKILLS_GETTING_STARTED.md:入门指南,含"代码审查技能"的完整示例
标准目录结构(详见 AGENTS.md):
skills/
<组名>-skills/ # 如 vue-skills、document-skills
my-skill/ # kebab-case,与 frontmatter name 一致
SKILL.md # 必需
examples/ # 可选:场景示例
references/ # 可选:参考文档
scripts/ # 可选:可执行脚本
frontmatter 两个必填字段:
| 字段 | 约束 |
|---|---|
name |
1–64 字符,小写字母、数字、连字符,必须与目录名一致 |
description |
1–1024 字符,说明技能做什么、何时触发,包含 "Use when..." 触发条件 |
💡
description是技能唯一的触发机制。写得具体(含中英文关键词),AI 才能准确判断何时激活它。
步骤一:准备环境并确定目标技能包
- 安装 Node.js / npm(使用 Skills CLI 需要)
- 在 SKILLS_INDEX.md 或 docs/skill-group-mapping.md 中找到与你的技能同组的包仓库,Fork 它
- 想参考现有技能的写法,可克隆导航仓库浏览文档:
git clone https://gitcode.com/partme-ai/full-stack-skills
建议先浏览同组已有技能(如 mermaid、maven-search),学习其结构与粒度。
步骤二:编写你的第一个 SKILL.md
以贡献一个 log-monitor 技能为例:
---
name: log-monitor
description: >
Analyzes application logs and alerts on anomalies.
Use when the user asks to check logs, monitor errors, or diagnose failures.
---
# Log Monitor
## How It Works
1. 读取指定日志文件
2. 按关键词分类错误级别
3. 输出结构化摘要
## Best Practices
- 优先展示 Critical 级别问题
编写时牢记 4 条最佳实践:
- 控制篇幅:正文建议 500 行以内,长内容拆到
references/,按需加载 - 单一职责:不要做"万能技能",一个技能只解决一类问题
- 确定性交给脚本:精确计算、格式转换写成
scripts/中的脚本,而不是让 AI 心算 - 渐进式披露:SKILL.md 只写核心流程,通过相对路径链接支撑文件
步骤三:本地测试与安装验证
在提交 PR 前,务必验证技能能被正确触发:
# Claude Code:复制到用户级技能目录
cp -r skills/log-monitor ~/.claude/skills/
然后在对话中说出触发语(如"帮我检查日志"),观察 AI 是否自动加载了该技能。
你也可以通过插件市场方式验证整个技能包的安装流程:
更多宿主兼容性与路径说明见 PLATFORM_GUIDE.md,安装命令速查见 QUICKSTART.md。
步骤四:提交 PR 完成上架
- 提交分支并发起 PR,说明:技能用途、触发场景、与现有技能的区别
- 等待 CI 检查:技能包的
SKILL.md变更会自动触发 skill-review.yml 工作流,PR 中会附上评分与优化建议,按提示迭代即可 - 若同时更新了导航仓库的目录信息,会触发 validate_catalog.py 校验包清单与技能计数是否一致
PR 自查清单:
- [ ]
name与目录名完全一致,kebab-case - [ ]
description不超过 1024 字符且包含 "Use when..." - [ ] 脚本以
#!/bin/bash开头并加set -e - [ ] 无硬编码的密钥或敏感信息
3 个提高合入率的技巧
- 触发词贴近用户语言:description 中同时覆盖中英文表达,如 "check logs / 检查日志"
- 参考高分技能:仓库内 openspec、ocrmypdf 等技能结构完整,是优秀范本
- 小步贡献:先提交一个聚焦的单一技能,被合入后再扩展成技能族
常见问题
- 技能没被触发? 检查 description 是否具体、关键词是否覆盖用户的说法(详见入门指南"常见问题"章节)
- 与现有技能重复? 先在 SKILLS_INDEX.md 中搜索同名或近义技能,避免重复建设
- 技能放错了包? 对照 docs/skill-group-mapping.md 确认分组归属
总结
向 full-stack-skills 贡献 Agent Skills 只需四步:选包 → 写 SKILL.md → 本地验证 → 提 PR。技能编写门槛并不高,真正的价值在于把你踩过的坑沉淀为 AI 可执行的标准化流程。现在,动手编写你的第一个技能包,让它出现在 788 个技能组成的市场中吧 🚀
登录后查看全文


