如何给full-stack-skills贡献技能:从零编写并上架你的第一个Agent Skills

原创2026-10-30 19:05:151,939 阅读
文章标签:文档知识库技术博客

如何给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 规范,技能以独立目录发布,可跨项目安装
  • 有回报:你的技能会被收录进 技能索引,供全社区一键安装

mermaid技能生成甘特图与流程图的效果示例

动手前:先搞懂 Agent Skills 的核心规范

一个技能本质上就是一个带 SKILL.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 才能准确判断何时激活它。

步骤一:准备环境并确定目标技能包

  1. 安装 Node.js / npm(使用 Skills CLI 需要)
  2. 在 SKILLS_INDEX.md 或 docs/skill-group-mapping.md 中找到与你的技能同组的包仓库,Fork 它
  3. 想参考现有技能的写法,可克隆导航仓库浏览文档:
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 是否自动加载了该技能。

Claude Code 中安装 full-stack-skills 技能插件的终端截图

你也可以通过插件市场方式验证整个技能包的安装流程:

Claude Code 成功添加 full-stack-skills 插件市场的截图

更多宿主兼容性与路径说明见 PLATFORM_GUIDE.md,安装命令速查见 QUICKSTART.md。

步骤四:提交 PR 完成上架

  1. 提交分支并发起 PR,说明:技能用途、触发场景、与现有技能的区别
  2. 等待 CI 检查:技能包的 SKILL.md 变更会自动触发 skill-review.yml 工作流,PR 中会附上评分与优化建议,按提示迭代即可
  3. 若同时更新了导航仓库的目录信息,会触发 validate_catalog.py 校验包清单与技能计数是否一致

PR 自查清单:

  • [ ] name 与目录名完全一致,kebab-case
  • [ ] description 不超过 1024 字符且包含 "Use when..."
  • [ ] 脚本以 #!/bin/bash 开头并加 set -e
  • [ ] 无硬编码的密钥或敏感信息

3 个提高合入率的技巧

  1. 触发词贴近用户语言:description 中同时覆盖中英文表达,如 "check logs / 检查日志"
  2. 参考高分技能:仓库内 openspec、ocrmypdf 等技能结构完整,是优秀范本
  3. 小步贡献:先提交一个聚焦的单一技能,被合入后再扩展成技能族

常见问题

  • 技能没被触发? 检查 description 是否具体、关键词是否覆盖用户的说法(详见入门指南"常见问题"章节)
  • 与现有技能重复? 先在 SKILLS_INDEX.md 中搜索同名或近义技能,避免重复建设
  • 技能放错了包? 对照 docs/skill-group-mapping.md 确认分组归属

总结

向 full-stack-skills 贡献 Agent Skills 只需四步:选包 → 写 SKILL.md → 本地验证 → 提 PR。技能编写门槛并不高,真正的价值在于把你踩过的坑沉淀为 AI 可执行的标准化流程。现在,动手编写你的第一个技能包,让它出现在 788 个技能组成的市场中吧 🚀

登录后查看全文
full-stack-skills