从零开发一个 AI Skill：完整实战指南 + 常用 Skill 推荐
本文不讲概念，只讲怎么干。从项目初始化到上线部署，每一步都给你可直接复制的代码和配置。最后附上我日常高频使用的 Skill 推荐清单。
一、项目结构：直接抄这个
别自己瞎建目录，标准结构长这样：
my-skill-name/ ├── SKILL.md # 核心指令文件（唯一入口） ├── scripts/ # 确定性逻辑脚本（Python/Bash） ├── references/ # API文档、Few-shot示例 └── assets/ # 模板、图片等静态资源初始化命令：
python scripts/init_skill.py my-skill--path~/.config/skills/三个硬性规则：
- 文件夹名 =
name字段 =module.json中的标识，三处必须一致 - 命名用 kebab-case（如
weekly-report-generator） - 一个 Skill 只干一件事，别贪多
二、SKILL.md 怎么写
这是整个 Skill 的灵魂文件，分两部分：YAML 头 + Markdown 正文。
YAML Frontmatter（身份证）
---name:weekly-report-generatordescription:"根据工作日志自动生成结构化周报。当用户说'写周报'、'总结本周工作'、'生成weekly report'时触发。"allowed-tools:Read,Write,Bashversion:1.0.0license:MIT---⚠️description是最关键的字段——AI 靠它判断什么时候调用你的 Skill。写清楚两件事：做什么+什么时候触发。
Markdown 正文（执行指令）
用祈使句，按模块写：
## 角色 你是一名资深项目经理，擅长从杂乱日志中提炼工作重点。 ## 执行步骤 1. 提取本周已完成的任务列表 2. 识别阻塞项和风险点 3. 生成下周计划建议 4. 按模板输出 ## 输入校验 - 如果用户未提供日志文本，主动询问 - 如果日志少于3条，提示补充 ## 输出格式 使用三级标题：### 本周进展 / ### 存在问题 / ### 下周计划 ## 示例 输入："周一完成了登录模块重构，周三修复了3个P2 bug，周五在评审新需求" 输出： ### 本周进展 - 完成登录模块重构 - 修复 3 个 P2 级别缺陷 - 参与新需求评审 ### 存在问题 - 无 ### 下周计划 - 跟进新需求排期防幻觉技巧：在正文里明确写"不要擅自补全业务规则"、“不要编造数据”，比你想的有用。
三、性能优化：省 Token 的核心手段
别把所有内容塞进一个文件，用三层分工：
| 层级 | 内容 | 加载时机 | 大小控制 |
|---|---|---|---|
| L1 | name + description | 常驻内存 | ~100 词 |
| L2 | SKILL.md 正文 | 触发后加载 | 尽量精简 |
| L3 | scripts/ + references/ | 按需调用 | 不占初始Token |
效果：初始加载从数万 Token 降到约 100 词，节省 60–90%。
另一个关键操作：确定性逻辑用脚本，别让 LLM 推理。
比如数据清洗、格式转换、文件重命名——这些写成 Python 脚本放scripts/里，执行速度快 3–100 倍，还不会出错。
四、测试：四层验证体系
| 层次 | 工具 | 什么时候跑 | 通过标准 |
|---|---|---|---|
| 单元测试 | pytest | 每次提交 | 覆盖率 ≥ 80% |
| 集成测试 | pytest + httpx | PR 合并前 | 全部通过 |
| 端到端 | 自研脚本 | 发布前 | 核心流程跑通 |
| 性能 | locust | 发布前 | P95 < 3s |
用例必须覆盖四类：
- ✅ 正向触发（该触发时触发）
- ❌ 负向不触发（不该触发时别乱触发）
- ⚠️ 边界条件（空输入、超长输入）
- 🛑 异常输入（乱码、注入攻击）
五、部署上线 & 常见坑
上线流程
提交审核 → 平台初审 → 功能测试 → 安全审计 → 上线
踩坑速查表
| 现象 | 原因 | 解法 |
|---|---|---|
| Skill 无响应 | name/目录/module.json 不一致 | 统一三处命名 |
| “function not found” | 方法名大小写不匹配 | 直接复制粘贴 functionName |
| 执行卡住超时 | 忘了回传完成信号 | 所有分支都调completeArkTSScriptInApp |
| API 被限流 | 并行请求太多 | 用 BufferedSender + 指数退避（1s→3s） |
| 输入无效报错 | 缺少必要参数 | ConditionalSkill 设默认值 |
API 稳定性配置（直接抄）
timeout:链路段P95 × 1.5retry:2次，指数退避（1s → 3s）circuit_breaker:5分钟内超时率>30% 自动熔断fallback:返回兜底文案 + 转人工六、常用推荐 Skill 清单
以下是我日常高频使用、经过生产验证的 Skill，按场景分类：
📝 效率工具类
| Skill | 干什么用 | 亮点 |
|---|---|---|
weekly-report-generator | 工作日志 → 结构化周报 | 自动提取进度/风险/计划，5秒出稿 |
meeting-notes-summarizer | 会议录音转写 → 结构化纪要 | 支持多说话人分离，自动提取待办和责任人 |
email-draft-assistant | 根据要点生成正式邮件 | 支持多种语气（正式/友好/催促），自动加称呼落款 |
💻 开发辅助类
| Skill | 干什么用 | 亮点 |
|---|---|---|
go-http-reviewer | Go HTTP 服务代码审查 | 聚焦安全漏洞、性能瓶颈、规范违规，比通用审查精准10倍 |
sql-query-optimizer | 慢查询分析 + 优化建议 | 给出索引建议、SQL重写方案，附执行计划对比 |
api-doc-sync | 代码变更自动同步 API 文档 | 监听 git diff，自动更新 OpenAPI/Swagger，告别文档滞后 |
commit-message-generator | 根据 diff 生成规范 commit message | 遵循 Conventional Commits，支持中英文 |
📊 数据处理类
| Skill | 干什么用 | 亮点 |
|---|---|---|
data-cleaning-pipeline | 脏数据清洗 + 标准化 | 封装 Python 脚本，比纯 LLM 处理快 50 倍，支持增量 |
csv-to-chart | CSV 数据 → 可视化图表 | 自动识别数据类型，选择最佳图表类型，输出 PNG/SVG |
log-anomaly-detector | 日志流异常检测 | 实时识别错误模式、性能退化，自动告警 + 根因定位 |
🔒 安全运维类
| Skill | 干什么用 | 亮点 |
|---|---|---|
secret-scanner | 代码仓库密钥泄露扫描 | 支持 200+ 种密钥模式，集成 CI/CD pipeline |
dependency-auditor | 依赖包安全漏洞审计 | 对接 CVE 数据库，按严重等级排序，给出升级建议 |
🎯 选型建议
- 优先选窄任务 Skill——"审查 Go HTTP 代码"比"做全栈开发"好用 10 倍
- 组合使用——
log-anomaly-detector+weekly-report-generator= 自动生成含异常分析的周报 - 看 description 质量——好的 Skill 会明确写触发词，差的只写一句模糊描述
- 有 scripts/ 目录的优先——说明作者把确定性逻辑脚本化了，执行更稳定
最后
别想太多，找一个你每天重复做的事（写周报、审代码、清数据），花 30 分钟把它封装成 Skill。第一次可能粗糙，但跑起来之后你会发现问题，然后迭代——这比看十篇教程有用。