AI 编程别乱装 Skill:按项目技术栈选,才真的有用

装了一堆 Skill，Claude Code照样给你写烂代码？问题通常不在 Skill，而在于你把 Skill 当成“能力插件”，却没有让它服务项目技术栈、架构边界和工程纪律。

系列导航

• 第 1 篇：11 天，1 个人 + AI，搭了一套网络监控系统
• 第 2 篇：不是 AI 替代人，而是分工变了：一次真实项目的提效与收口复盘

这篇文章不做 Skills 市场清单，也不按热度推荐。它只回答一个更实用的问题：

在一个真实的 FastAPI + Vue 3 内部监控系统里，哪些 Skill 真有用，应该怎么触发，哪些反而不该引入？

本文基于 H-NetInsight 网络监控系统的实践整理。这个项目的技术栈很典型：

• 后端：Python 3.11+、FastAPI、SQLAlchemy async、Alembic、APScheduler、aiohttp
• 数据：默认 SQLite，兼容 MySQL 8.0 + asyncmy
• 前端：Vue 3 + TypeScript、Vite、Element Plus、ECharts、Pinia
• 质量：pytest、pytest-asyncio、pytest-cov、vitest、ruff、mypy --strict
• 部署：Docker、Docker Compose、Nginx

项目边界也很明确：单体优先、TDD 强制、异步优先、安全默认，不引入 Redis 或其它缓存层，不提前拆微服务。

所以，Skill 的选择标准不是“哪个火”，而是：

1. 能不能约束 Agent 按这个技术栈写代码
2. 能不能减少项目里真实发生过的错误
3. 能不能把团队的工程规则变成可触发的工作流
4. 会不会把本项目不需要的东西带进来

一、Skill 不是外挂，是工作规程

很多人装 Skill 的姿势是这样的：

npx skills add fastapi vue docker mysql redis security ...

然后期待 Claude 自动变强。

但 Skill 真正做的事情不是“增加模型能力”，而是把一段项目经验、检查清单或操作步骤放进 Claude Code 的可触发上下文里。

它大致分三层加载：

• 元数据：SKILL.md 里的 name 和 description，用来判断什么时候该触发
• 正文指令：触发后才进入上下文，告诉 Agent 具体怎么做
• 辅助资源：scripts/、references/、templates/，需要时再读取或执行

这里最关键的是 description。Claude 不是按关键词正则匹配，而是靠描述语义判断要不要加载 Skill。描述写得宽，容易乱触发；描述写得窄，又可能该用时用不上。

还有两个 frontmatter 字段很容易被忽略：

• disable-model-invocation: true：禁止 Claude 自动调用，只能用户手动触发。适合部署、发版、提交这类有副作用的动作。
• user-invocable: false：用户在 / 菜单里看不到，但 Claude Code 可以自动触发。适合辅助知识型 Skill。

比如 fastapi-async-patterns 在本机配置里就是 user-invocable: false。它更像内部参考，不应该在文章里写成主用户命令。

二、先避开 4 个坑

在按技术栈选 Skill 之前，先讲几个我更在意的坑。

1. 同类 Skill 堆太多，Agent 路由会漂

如果你同时装了 parse-pdf、read_pdf、pdf-extract、document-pdf，每个都说自己能处理 PDF，主 Agent 就会在多个描述之间摇摆。

这类漂移在业务项目里很危险：A 会话用这个 Skill，B 会话用另一个 Skill，同一个任务的执行路径不一致，后面复盘也不知道规则到底来自哪里。

我的做法是：同一能力只保留一个主 Skill。其它 Skill 要么归档，要么降级成参考资料。

2. 外部 Skill 不审查，等于信任外部脚本

Skill 可以带 scripts/，也可以声明 allowed-tools。它不等于默认拥有无限 shell 权限，但在 workspace trust、工具权限或用户批准后，确实可能执行脚本和命令。

所以新 Skill 引入前至少检查四件事：

• SKILL.md 有没有过宽的触发描述
• allowed-tools 是否预批准了高风险工具
• scripts/ 是否拼接了未清洗输入
• 来源是否是官方、可信社区或内部审核仓库

3. SKILL.md 太长，反而会稀释重点

Skill 不是知识库全文。正文越长，模型越容易抓不到真正的硬约束。

我的经验是：SKILL.md 只放必须遵守的规则和执行入口，长文档放进 references/，脚本放进 scripts/。

4. 项目约束不能靠通用 Skill 兜底

通用 fastapi Skill 会告诉你 FastAPI 最佳实践，但它不知道 H-NetInsight 的具体规则：

• 所有新功能必须 TDD
• 登录限流不能引入 Redis
• HTTP Probe 的 response_time_ms 不能复用 duration_ms
• 前端时间格式化必须走统一工具
• Docker builder 阶段不能设置 NODE_ENV=production

这些规则应该写进项目级文档、项目 wrapper skill 或仓库检查脚本，而不是期待外部 Skill 猜到。

三、后端：FastAPI + SQLAlchemy async + Probe 并发

H-NetInsight 后端的关键不是“写几个 API”，而是异步链路要稳。

项目约束：

• API 层使用 FastAPI + Pydantic
• 数据库使用 SQLAlchemy async
• 探测逻辑全部异步执行
• 调度器需要真实限制全局并发
• 新功能和修复必须先有测试

Agent 容易翻车的地方：

• 在路由里绕过 Depends()，直接拿全局 session
• 在 async def 里调用阻塞 I/O
• 用 gather(*tasks) 一把撒出去，没有 Semaphore
• 服务层用了 noload()，API 层还去读 ORM 关系
• 用 MAX(checked_at) + GROUP BY 查最新记录，遇到相同时间戳就重复

推荐 Skill：

• fastapi：约束路由、依赖注入、Pydantic 契约
• fastapi-async-patterns：辅助处理 FastAPI 异步模式，本地配置为自动触发参考
• async-python-patterns：约束 Semaphore、超时、阻塞隔离
• sqlalchemy-alembic-expert-best-practices-code-review：约束迁移、session、窗口函数
• python-testing-patterns：强化 TDD、parametrize、fixture 隔离

触发方式：

• 写 API、Schema、依赖注入时，主用 /fastapi
• 排查并发、超时、阻塞调用时，用 /async-python-patterns
• 写模型、迁移、复杂查询时，用 /sqlalchemy-alembic-expert-best-practices-code-review
• 写测试或修复 Bug 时，用 /python-testing-patterns
• fastapi-async-patterns 作为自动触发辅助，不把它当主入口

一个好提示词可以这样写：

按本项目 FastAPI + SQLAlchemy async 约束，实现任务详情接口。先补失败测试，再写实现。注意 session 生命周期、Pydantic 响应模型、同 checked_at 时按 id desc 取最新。

这比单纯说“帮我写个接口”靠谱得多。

四、数据库：默认 SQLite，兼容 MySQL，但不引入 Redis

这个项目默认 SQLite 单实例部署，但又保留 MySQL 8.0 兼容路径。这决定了数据库相关 Skill 的关注点不是“高级数据库架构”，而是兼容性和防御性查询。

项目约束：

• SQLite 使用 sqlite+aiosqlite://
• MySQL 使用 mysql+asyncmy://
• 查询要兼容 SQLite 和 MySQL 8.0
• 不引入 Redis 或其它缓存层

Agent 容易翻车的地方：

• sa.String() 不写长度，SQLite 没事，MySQL 失败
• TEXT 列设置 server_default，SQLite 能跑，MySQL 不允许
• groups 这类保留字在原生 SQL 中没转义
• MySQL 密码里有 @、!、# 却没 URL 编码
• 空列表直接拼 WHERE id IN ()

推荐 Skill：

• mysql-best-practices：处理 MySQL 保留字、VARCHAR 长度、TEXT 默认值、URL 编码
• sqlalchemy-alembic-expert-best-practices-code-review：处理迁移链、窗口函数、ORM 查询边界
• python-performance-optimization：慢接口排查时区分数据库层和应用层

触发方式：

• 改 ORM 模型或 Alembic 迁移，用 /sqlalchemy-alembic-expert-best-practices-code-review
• 涉及 MySQL 兼容、连接串、保留字，用 /mysql-best-practices
• MySQL 本地执行很快但 API 很慢，用 /python-performance-optimization

这里特别强调：H-NetInsight v1 不引入 Redis。登录限流、缓存、队列这类需求都要先回到项目边界，不能因为装了相关外部 Skill 就顺手加缓存层。

五、前端：Vue 3 工程化，不是堆组件

前端栈看起来常规：Vue 3 + TypeScript + Element Plus + ECharts + Pinia。真正容易出问题的是契约漂移和状态散乱。

项目约束：

• Vue 3 使用 Composition API + <script setup>
• TypeScript 开 strict
• 全局状态用 Pinia
• UI 组件库使用 Element Plus，并注入中文语言包
• 图表使用 ECharts
• 前后端类型要尽量从 OpenAPI 同步

Agent 容易翻车的地方：

• 新组件写成 Options API
• 直接解构 Pinia store，导致响应性丢失
• 表单只校验 config，漏掉后端顶层必填字段
• ECharts 组件卸载时不 dispose
• 前端手写 API 类型，后端字段改了之后漂移
• 在组件里到处拼 ${value} ms、${value}%，绕过统一格式化

推荐 Skill：

• vue：约束 Composition API、<script setup>、Props 类型
• vue-best-practices：约束组件通信、composable、v-for :key
• pinia：约束 store 拆分、actions、storeToRefs
• element-plus-vue3：约束表单校验、对话框、中文配置
• echarts：约束 dispose、resize、响应式 option
• typescript-advanced-types：约束 strict、类型派生、避免 any
• openapi-to-typescript：减少前后端契约漂移

触发方式：

• 写页面或组件，用 /vue 和 /vue-best-practices
• 写全局状态，用 /pinia
• 写表单、表格、弹窗，用 /element-plus-vue3
• 写 Dashboard、趋势图、证书看板，用 /echarts
• 对齐 API 类型，用 /openapi-to-typescript

对这个项目来说，前端 Skill 的价值不是“生成漂亮页面”，而是让 Agent 不要破坏运行时契约。

六、质量与安全：TDD、类型、响应头、认证链路

H-NetInsight 是监控系统，安全和可靠性比页面花活更重要。

项目约束：

• 所有新功能和 Bug 修复先写测试
• Python 使用 ruff、mypy --strict
• 前端使用 vitest
• 密码 bcrypt 哈希
• 敏感字段加密存储
• 登录接口限流
• API 安全响应头必须输出
• 认证载体前后端一致

Agent 容易翻车的地方：

• 先写实现，再补一个只证明“代码能跑”的测试
• 对外部通知通道以外的逻辑过度 Mock
• 登录失败 401 被全局拦截器吞掉，页面不显示错误
• 后端设置 HttpOnly Cookie，前端测试却用 document.cookie 读 token
• 业务失败返回 ok=false，前端只看 HTTP 200 就弹成功

推荐 Skill：

• python-testing-patterns：约束 pytest、parametrize、fixture 隔离
• code-review：从正确性、安全、可维护性三层审查
• security-best-practices：约束加密、JWT、限流、安全头
• code-refactoring：约束小步重构和行为不变
• git-commit：约束 Conventional Commits 和提交粒度

触发方式：

• 接到 Bug，先触发 /python-testing-patterns 写复现测试
• 改认证、安全、敏感配置，触发 /security-best-practices
• 完成一组改动后，用 /code-review 做自查
• 只改结构不改行为时，用 /code-refactoring
• 提交前用 /git-commit

这里有个很实用的规则：如果一个 Bug 暴露了缺失的工程约束，就把这个约束沉淀到文档、测试或项目 Skill，而不是只修当前代码。

七、部署：Docker Compose 要能在内网稳定构建

部署相关 Skill 最容易把文章写成 Docker 教程。但在 H-NetInsight 里，重点其实很具体：国内网络环境、前端构建依赖、健康检查、端口冲突。

项目约束：

• Docker + Docker Compose 单实例部署
• 后端容器内监听 8000，宿主机映射 8001
• 前端 builder 阶段必须安装 devDependencies
• 构建参数要支持国内镜像源
• ICMP 探测需要 CAP_NET_RAW

Agent 容易翻车的地方：

• builder 阶段设置 NODE_ENV=production，导致 vite、vue-tsc 没安装
• Compose 用 ${VAR:-} 传空字符串，覆盖 Dockerfile 默认 ARG
• 健康检查缺失，前端容器先启动但后端还没 ready
• ICMP 探测容器没加能力，线上才发现 ping 不通

推荐 Skill：

• docker-expert：容器安全、多阶段构建、非 root 用户、能力控制
• multi-stage-dockerfile：构建缓存、ARG 默认值、镜像源
• docker-compose-orchestration：健康检查、服务依赖、端口映射

触发方式：

• 改 Dockerfile，用 /docker-expert 和 /multi-stage-dockerfile
• 改 Compose 编排，用 /docker-compose-orchestration
• 部署构建失败，优先检查 NODE_ENV、build args、镜像源和健康检查

八、架构：单体优先，项目 Skill 兜住边界

最后说架构。

通用 architecture-patterns 会告诉你 Clean Architecture、Hexagonal Architecture、Repository Pattern 等等。这些都可能有价值，但 H-NetInsight v1 的第一原则是简单性。

项目约束：

• 单体架构
• 不拆微服务
• 不做多租户
• 不引入外部 APM
• PostgreSQL 迁移属于后续专题
• Redis 不在当前范围

Agent 容易翻车的地方：

• 为了“专业”引入 Manager / Provider / Builder 多层抽象
• 把轻量监控系统设计成微服务
• 为未来需求提前加缓存、队列、插件系统
• 为了迁移 MySQL 顺手改掉 SQLite 单实例假设

推荐 Skill：

• architecture-patterns：提醒关注点分离、配置外置、错误分层
• 项目级规则文档：约束哪些东西不能做
• 项目 wrapper skill：把 H-NetInsight 的硬规则放到 Agent 可触发上下文里

触发方式：

• 做模块边界、服务层拆分、技术方案评审时，用 /architecture-patterns
• 但一旦通用架构建议和项目约束冲突，以项目约束为准

我的建议是：通用 Skill 负责技术最佳实践，项目 Skill 负责业务边界和禁止事项。

九、更低门槛：把 23 个 Skill 蒸馏成一个调度入口

上面的分层仍然有一个问题：对真正的一线使用者来说，记住 20 多个 Skill 的名字和触发场景，成本还是太高。

更好的做法不是继续教大家背命令，而是把通用 Skill 蒸馏成少数几个项目能力包，再用一个项目级 router skill 做入口。

可以把 H-NetInsight 的 Skill 使用方式压缩成 5 类：

然后再做一个项目级入口，比如 netinsight-skill-router。

它不需要复制所有通用 Skill 的知识，也不应该变成另一个巨大的 SKILL.md。它只做三件事：

1. 先读取 H-NetInsight 的项目硬约束：TDD、单体优先、异步优先、安全默认、不引入 Redis、不提前拆服务。
2. 根据任务意图选择能力包：后端走 backend-api-stack，前端走 frontend-vue-stack，数据兼容走 data-compat-stack。
3. 当通用 Skill 建议和项目规则冲突时，以项目规则和仓库验证脚本为准。

它的触发描述可以写得更接近日常语言：

---name: netinsight-skill-routerdescription: H-NetInsight 项目 Skill 路由器。处理本仓库中的后端 API 变更、Vue 前端开发、数据库迁移、Probe 调度、认证、安全、测试、Docker 部署、文档、Bug 修复或代码审查时自动使用。它会选择合适的蒸馏技术栈指南，并在通用技术指导之前优先应用项目规则。---

这样，用户不需要说：

请使用 fastapi、async-python-patterns、sqlalchemy-alembic 和 python-testing-patterns 修复这个接口。

只需要说：

修复监控详情页最近结果显示不准的问题。

router skill 就应该把任务路由到：

• backend-api-stack：检查接口、服务层、Pydantic 响应模型
• data-compat-stack：检查最新记录查询是否用了稳定排序
• quality-safety-stack：先补复现测试，再做最小修复

这才是 Skill 在团队里真正可持续的用法：人不记 Skill，项目替人调度 Skill。

十、H-NetInsight 核心推荐 Skills 一览

如果要落到安装层面，下面这张表仍然适合收藏。注意：命令名取决于安装后的目录名，实际使用时以 Claude Code 的 / 菜单和本机 Skill 配置为准。

十一、安装命令

可以直接执行下面的 Bash 命令。注意：反斜杠 \ 是 Bash 续行符，不能直接复制到 PowerShell；每行末尾的 \ 后面也不要带空格或中文标点。

# 一键安装 H-NetInsight 核心推荐 Skillsnpx skills add \  fastapi/fastapi@fastapi \  thebushidocollective/han@fastapi-async-patterns \  wispbit-ai/skills@sqlalchemy-alembic-expert-best-practices-code-review \  wshobson/agents@async-python-patterns \  wshobson/agents@python-performance-optimization \  wshobson/agents@python-testing-patterns \  antfu/skills@vue \  hyf0/vue-skills@vue-best-practices \  antfu/skills@pinia \  antfu/skills@vueuse-functions \  teachingai/full-stack-skills@element-plus-vue3 \  vamseeachanta/workspace-hub@echarts \  wshobson/agents@typescript-advanced-types \  softaworks/agent-toolkit@openapi-to-typescript \  mindrally/skills@mysql-best-practices \  supercent-io/skills-template@code-review \  supercent-io/skills-template@security-best-practices \  supercent-io/skills-template@code-refactoring \  github/awesome-copilot@git-commit \  sickn33/antigravity-awesome-skills@docker-expert \  github/awesome-copilot@multi-stage-dockerfile \  manutej/luxor-claude-marketplace@docker-compose-orchestration \  wshobson/agents@architecture-patterns \  -g -y

更多 Skills 发现：npx skills find <关键词> | Skills 市场：https://skills.sh/

最后：不要让 Skill 替你做架构决策

如果只能带走三句话，我希望是这三句：

1. Skill 要按项目技术栈选，不要按市场热度选。
2. 让项目级 router skill 调度能力包，不要让人手动记住每个 Skill。
3. 每次真实故障暴露出的规则，都应该沉淀成测试、文档、脚本或项目 Skill。

我的实际做法是：

• 先用项目文档定义技术栈和不做事项
• 再把通用 Skill 蒸馏成后端、前端、数据、安全、交付这几类能力包
• 最后用项目级 router skill 兜住 TDD、安全、认证、时间、Probe、部署这些本项目硬约束

本文的核心实践来自 H-NetInsight 项目落地过程；清单中的外部 Skill 仍需按你的实际安装环境、命令名和权限配置复核。

本文基于 H-NetInsight 项目的 AI Agent Skills 实践总结