# Skill Architect

> 设计和架构 agent skill——判断 skill/suite/command/plugin 形态，定义模块边界与路由，将隐性经验提炼为可移植 skill 结构。评测/benchmark/触发优化请交给官方 skill-creator。

- **Type:** Skill
- **Install:** `agentstack add skill-zht043-agent-skill-architect-agent-skill-architect`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zht043](https://agentstack.voostack.com/s/zht043)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zht043](https://github.com/zht043)
- **Source:** https://github.com/zht043/agent-skill-architect

## Install

```sh
agentstack add skill-zht043-agent-skill-architect-agent-skill-architect
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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）
```yaml
---
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](https://github.com/zht043)
- **Source:** [zht043/agent-skill-architect](https://github.com/zht043/agent-skill-architect)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zht043-agent-skill-architect-agent-skill-architect
- Seller: https://agentstack.voostack.com/s/zht043
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.