Skill Architect

Skill Architect

概述

通过探索打通能力，再提炼为标准化 skill。一个 skill 只做一件事。 本 skill 专注于架构设计与能力沉淀，与官方 skill-creator 互补：

• skill-architect：结构设计、边界划分、路由设计、经验提炼
• 官方 skill-creator：eval 生成、benchmark 对比、description 触发优化、迭代改进闭环

何时使用

• 需要从零设计一个新 skill 或 skill suite
• 需要判断应该做 skill、suite、command wrapper 还是 plugin
• 需要从探索/聊天记录中提炼稳定结构
• 需要为已有 skill 做架构重构
• 需要检查 skill 的可移植性和独立性

何时不使用

• 已有结构稳定的 skill，只需做 eval/trigger 优化 → 使用官方 skill-creator
• 只是想运行/调用一个已有 skill
• 纯代码实现，不涉及 skill 设计

形态决策（Scope Decision）

在开始设计前，先判断目标产出的形态：

| 信号 | 推荐形态 | |------|----------| | 功能单一、文件少 | 单体 Skill | | 多个相关子模块、共享配置 | Skill Suite | | 高副作用操作、参数明确、用户经常直接调用 | Command Wrapper | | 需要降低安装门槛、打包多个 skill、附带 MCP 配置 | Plugin | | 不确定 | 从单体 Skill 开始，按需升级 |

Skill 类型

• 能力型（capability）：封装具体操作能力，重心在脚本，SKILL.md 做调度说明
• 流程型（process）：指导工作流程方法论，重心在 SKILL.md 本身

Skill 形态

单体 Skill

功能单一、文件少的 skill，平铺结构。

/
  SKILL.md             # 核心文档（给 agent 看，精简可靠）
  README.md            # 使用说明（给用户看，含 prompt 示例）
  config.example.yaml  # 可选，配置模板
  scripts/             # 可选，工具脚本目录
  references/          # 可选，版本表、排障、长示例
  evals/               # 触发评测、任务 prompt、验收标准

Skill Suite

多个相关子模块共同组成完整能力时，使用 suite 结构。

/
  SKILL.md             # Suite 入口：总览 + 路由（不含执行细节）
  README.md            # 使用说明（整个 suite）
  config.example.yaml  # 可选，共享配置模板
  _lib/                # 可选，共享工具脚本
  /            # 子模块目录
    SKILL.md           # 子模块文档
    scripts/           # 可选，子模块专属脚本
    references/        # 可选，子模块参考资料
  references/          # Suite 级参考资料
  evals/               # Suite 级评测

SKILL.md 头部格式

采用双层元数据模型：

第一层：Portable Core（放在 SKILL.md）

---
name: skill-name
description: 精准描述何时应该触发、何时不该触发（含核心动词、关键名词、同义词）
---

仅保留 name 和 description。这两个字段是跨 agent 的核心协议。

第二层：平台适配层

• Claude Code：需要时添加 disable-model-invocation、user-invocable、allowed-tools、context: fork、agent、paths 等
• Codex：需要时添加 agents/openai.yaml、.codex-plugin/plugin.json

第三层：人类/目录元数据

type / tags / risk_level / platform / version 等信息放到 references/skill-manifest.md。

description 编写指南

1. 包含核心动词（安装/部署/监控/导出/生成）
2. 列出关键名词（技术栈、工具名、协议名）
3. 加入同义词覆盖不同表述
4. 具体优于笼统
5. 一句话，不超过 50 字

内容分层规则

SKILL.md 只放：

• 何时用 / 何时不用
• 路由规则 / 执行流程
• 最小安全约束
• 脚本与 references 指针

references/ 放：

• 版本表、兼容性矩阵
• 排障手册
• 长示例、背景说明

scripts/ 放：

• 稳定的执行动作
• 环境探测
• 自包含 helper

开发流程

探索阶段（可选）

目标：打通能力，验证可行性。

• 用户主导 / agent 主导 / 协作探索
• 记录：关键命令、参数、踩坑点、成功路径

提炼阶段

1. 判断类型（能力型 or 流程型）和形态（单体 or suite）
2. 按模板生成 SKILL.md（精简，去除冗余）
3. 提炼可复用命令为脚本
4. 生成 config.example.yaml（如适用）
5. 生成 README.md
6. 移动易变内容到 references/

收尾

• 新会话验证 skill 能否被正确执行
• 入库发布

Handoff：交给官方 skill-creator

当以下条件满足时，建议将 skill 交给官方 skill-creator 做进一步优化：

• 拓扑、边界和模块拆分已稳定
• SKILL.md / scripts / references 结构已确定
• 需要生成 trigger eval 和 benchmark

官方 skill-creator 擅长：

• eval 生成（trigger-eval.json）
• with-skill vs no-skill 对比
• description 触发优化
• 迭代改进闭环

Portable Core 检查清单

• [ ] SKILL.md 不依赖 Claude 私有特性也能读懂
• [ ] SKILL.md 不依赖 Codex 专属 metadata 也能读懂
• [ ] 持久稳定的 workflow logic 在 portable layer
• [ ] 平台控制旋钮在 adapter layer
• [ ] 无硬编码引用其他 skill 名称

Split-Readiness 检查

• [ ] 不假设 monorepo 一定存在
• [ ] 不写死 sibling path
• [ ] README 不默认依赖其他 repo 同时安装
• [ ] 能力依赖用描述而非具名引用

Plugin 包装决策

| 场景 | 建议 | |------|------| | 个人使用、实验阶段 | 本地 skill 即可 | | 团队分发、降低安装门槛 | 升级为 plugin | | 需要附带 MCP / app 配置 | 升级为 plugin | | 打包多个 skill 组合 | 升级为 plugin |

规范约束

• 文档语言：中文
• SKILL.md 面向 agent：精简、可靠、无冗余
• README.md 面向用户：使用方法、prompt 示例
• 能力型 SKILL.md ≤ 1KB，流程型 ≤ 3KB
• 脚本统一放 scripts/，须自包含、可独立运行
• 脚本 ≤ 200 行，超过则拆分
• 禁止具名引用其他 skill：描述"需要什么能力"，让 agent 自行寻找
• 高副作用操作偏向手动触发

跨平台规范

• 声明目标平台
• 远程场景分别声明客户端和服务端平台
• 脚本识别运行环境并适配
• 跨平台传输注意换行符差异

Token 约束

• 探索记录精简关键命令，不保存完整输出
• 文档一次性写入，不重复展示
• 验证只输出关键状态

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zht043
• Source: zht043/agent-skill-architect
• License: MIT

Install and usage instructions live in the source repository linked above.