背景

随着 AI Coding Agent 的普及，越来越多的开发者开始为自己的工作流编写 Skills（技能）。

最初只有几个简单脚本时，管理起来并不困难：

skill-a.sh
skill-b.sh
skill-c.sh

但随着数量增加，很快会遇到一些问题：

• 配置散落在多个脚本中

• 相同逻辑被重复实现

• 环境信息到处复制

• 文档和代码逐渐脱节

• 新增 Skill 成本越来越高

因此需要一套能够长期维护和扩展的工程化组织方式。

---

设计目标

设计框架时，我主要考虑了以下目标：

1. 配置集中管理

避免出现：

skill-a
  host=xxx

skill-b
  host=xxx

skill-c
  host=xxx

环境配置应该只有一个来源。

---

2. 技能职责单一

每个 Skill 只解决一个问题。

例如：

check_environment
cleanup_logs
diagnose_request

而不是做成一个“大而全”的脚本。

---

3. 知识与代码分离

很多经验知识其实并不属于代码：

例如：

某类请求只会经过节点A

某个ID从节点B开始生成

某服务不参与某类流程

这些知识应该独立维护。

---

4. 方便未来扩展

未来增加：

测试环境
预发布环境
生产环境

时，不应该修改 Skill 本身。

---

推荐目录结构

最终采用如下结构：

.codex-dev

├── README.md

├── shared
│
│   ├── env
│   ├── knowledge
│   ├── data
│   ├── examples
│   ├── scripts
│   ├── log-patterns
│   ├── sop
│   └── templates
│
└── skills

---

shared/env

环境配置目录。

例如：

env/

development.yaml
testing.yaml
staging.yaml
production.yaml

存放：

• 主机信息

• 服务定义

• 日志位置

• 默认参数

• 流程定义

配置文件成为整个系统的 Single Source of Truth。

---

shared/scripts

公共脚本目录。

例如：

ssh_exec.sh
yaml_query.sh
log_search.sh

多个 Skill 可以直接复用。

这样可以避免：

每个 Skill 都实现一遍 SSH

的问题。

---

shared/knowledge

知识库目录。

这是整个框架中最容易被忽视但最有价值的部分。

很多内容并不适合写进代码：

系统架构

流程规则

特殊行为

已知限制

故障经验

这些内容更适合沉淀为知识文档。

例如：

architecture.md

service_a.md

service_b.md

这样 AI 在分析问题时能够获得正确上下文。

---

shared/data

结构化数据目录。

这里与知识库最大的区别是：

knowledge

面向阅读：

为什么这样设计

data

面向程序：

service_alias:
  svc1: service_a
  svc2: service_b

推荐只保存：

• YAML

• JSON

• CSV

等结构化数据。

---

shared/examples

案例库。

保存真实问题和分析过程。

例如：

request_timeout

authentication_failed

routing_error

每个案例包含：

logs/

analysis.md

result.md

随着积累，这部分往往会成为最有价值的资产。

---

shared/log-patterns

日志规则库。

例如：

authentication_failure:
  - "Unauthorized"
  - "Authentication failed"

timeout:
  - "Request timeout"

多个 Skill 可以共享同一套规则。

---

shared/sop

标准操作流程。

例如：

服务重启

配置检查

故障排查

避免经验只存在于某个人脑中。

---

shared/templates

模板库。

例如：

问题分析报告

故障复盘报告

变更记录

让输出结果保持统一格式。

---

Skills 的职责

Skill 应该尽量轻量。

例如：

skills/

check_environment

diagnose_request

cleanup_logs

每个 Skill：

读取配置
↓
执行动作
↓
输出结果

而不是：

维护配置
维护知识
维护数据
执行动作

全部混在一起。

---

一个重要原则

在整个设计过程中，我坚持一个原则：

配置只维护一份。

例如：

环境定义

只存在于：

shared/env

而不会同时出现在：

Skill
README
脚本

这样可以避免配置漂移（Configuration Drift）。

---

持续演进

随着 Skill 数量增加，这套结构仍然能够保持稳定：

新增 Skill
无需修改已有 Skill

新增环境
无需修改 Skill

新增知识
无需修改代码

新增案例
无需修改逻辑

系统能够自然扩展，而不会逐渐失控。

---

总结

对于 AI Skills 工程来说，最重要的并不是写出多少 Skill，而是建立清晰的边界：

• 配置归配置

• 知识归知识

• 数据归数据

• Skill 只负责执行

当目录结构能够准确反映这些职责时，整个系统会更容易维护，也更容易随着项目规模增长而演进。

很多时候，好的工程设计并不是增加更多代码，而是让每类信息都待在最合适的位置。