一、问题与背景大多数 Agent 项目的代码库里都会看到这样的目录结构agent-ba/ prompts/ system.md examples.md tools/ jira.py wiki.py agent-sa/ prompts/ system.md tools/ arch.py agent-pm/ ...看似清晰实则隐患重重重复每个角色的 system prompt 都有一段你是专业的 XXX的套话改一处要同步十几处。隐式依赖BA 的提示词里提到了某个 Jira 字段但 SA 的工具集并不知道这件事跨 Agent 调用就出错。不可评估没有版本号没有变更记录没有回归用例“我也不知道这次改完效果是变好还是变坏”。不可发现新人想知道团队里现在有哪些现成的能力只能挨个问同事。这些还不是最要命的。最致命的是没有契约当 BA 把一段 Markdown 交给 SASA 只能猜这段内容是什么格式、是结构化还是非结构化、是必填还是选填。这种靠默契的协作在前两个 Agent 之间还能跑通一旦涉及五个、十个 Agent整个系统就变成了一个巨大的隐藏耦合网络任何一个角色的 prompt 改动都可能让另一端静默失效。当 Agent 从 demo 走向生产这些问题会被指数级放大。二、产品规格Agent Skill Warehousemcp.smartmoves.com.cn 把上述散落的能力碎片重组为标准化的 Skill 资产。每个 Skill 是一个自描述的目录核心文件结构如下ba-master/ SKILL.md # 元信息name, version, owner, tags instruction/ # 指令层角色定义、行为约束 knowledge/ # 知识层领域文档、FAQ execution/ # 执行层MCP 工具、脚本、API evaluation/ # 评测层基准用例与评分脚本 CHANGELOG.md # 变更日志核心能力一览能力含义工程类比版本管理语义化版本号 不可变发布npm version可发现性标签、依赖图、全文搜索PyPI search可评估性内置基准 回归用例unit test生命周期草稿/发布/弃用三态Maven release三、技术架构整体技术栈选择了轻后端、重前端、标准协议的路线┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Web 门户 │ ←→ │ FastAPI 后端 │ ←→ │ PostgreSQL │ │ ReactVite │ │ (Registry API) │ │ (元数据) │ └──────────────┘ └────────┬─────────┘ └──────────────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ MinIO │ │ Qdrant │ │ MCP │ │ (文件) │ │ (向量) │ │ (运行时) │ └──────────┘ └──────────┘ └──────────┘关键设计取舍元数据进 PG内容进 MinIO目录索引、版本关系等结构化数据走关系型数据库Skill 的大体积资源文档、脚本、二进制走对象存储避免 DB 膨胀。检索走 Qdrant用户搜索擅长画 UML 的技能后台把指令层和知识层内容 Embedding 后检索召回排序由向量数据库完成。消费走 MCP运行时不必为每个 Agent 框架写适配层——只要支持 MCP就能pull任意 Skill 到本地上下文。评测本地化评测用例随 Skill 一起发布CI 流水线在 Agent 端执行平台只负责版本打分不接触业务数据。这些拆分原则的共同出发点是让仓库保持轻仓库只负责“指示与打分”不负责“重计算与执行”。这一边界划定后平台才有可能以开源的方式快速发展而不是被某个重量级业务拖慢节奏。还有一个容易被忽略的设计原则Skill 不绑定模型。同一个 SKILL.md 既可以在 GPT-4 上跑也可以在 Claude 上跑还可以在本地开源模型上跑。仓库不关心你用谁家的大脑只负责保证你拿到的能力描述是清晰的、可复现的、可对比的。这让平台在中立性上天然优于“某家模型厂商提供的 Agent 商店”。四、成果与收获把仓库跑起来后几个有意思的变化出现了冲突暴露在前之前 BA 改了提示词、SA 不知道等集成时才发现语义对不上。现在所有变更通过 PR 走仓库跨角色影响一目了然。Skill 出现了明星和僵尸通过下载统计团队清晰地看到了哪些 Skill 被高频复用、哪些无人问津可以果断下架后者。评测分数成了健康指标每次发布都跑基准仓库首页就能看到分数趋势质量回归立刻被发现。新人首日就上手新人第一天 clone 仓库、跑评测、看 README就能跑通端到端的演示。更深入的变化是能力交换成为可能当仓库里某个团队的 SA-Master 做得足够好另一个团队可以直接复用而不用重复造轮子。这种跨团队的知识复用才是 Skill 仓库真正的价值——它让 Agent 能力也像代码一样成为了可流动的资产。五、实践成果网站地址plan.smartmoves.com.cn这套架构已经在真实业务中跑通——该站点是 Agent Skill Warehousemcp.smartmoves.com.cn的实践入口把 BA-Master / SA-Master / PM-Master 三个技能集的能力具象化为可视化的智能规划工作台欢迎访问体验。访问站点时建议留意两点一是各角色 Agent 的交付物是否清晰可读二是交接处的格式是不是严格遵循了 output_contract。这两个点是衡量一个 Skill 仓库是否“上了轨道”的最直观信号。