从0到1搭建AI-Native组织：以Skills为核心的可复用LLM能力资产体系

AI-Native 组织的研发体系，核心资产正在从代码仓库转向可组合的 Skills。所谓 AI-Native，不是简单地把大模型接入现有后台，而是把模型调用、检索增强、智能体编排、评测反馈这些能力当作软件系统的原生组成部分来设计。此时最大的问题不是写出一个能回答问题的函数，而是如何让组织内的 Skills 被找到、被复用、被稳定升级。把 AI-Native SDLC Playbook 落到工程现场，第一步往往不是铺开 Agent，而是先定义 Skills 的标准结构和扩展机制。

如果你正在搭建企业级 LLM 应用平台，或刚开始整理 Agent 的提示词和工具调用，下面会从一份可运行的 Skill 模板开始，逐步拆解注册、评测、发布和规模化复用。整条主线围绕一个问题：当 AI-Native 组织不再按“项目”交付，而是按“能力资产”运转时，Skills 应该如何被结构化、沉淀、授权和扩展。

1. 为什么 AI-Native SDLC 要以 Skills 为基本单元

1.1 从“项目交付”到“能力资产”

传统研发团队按项目组织交付物，项目结束后代码进入 Git 仓库，经验留在团队成员脑中。项目之间即使有大量相似逻辑，也很少被主动抽成可复用组件。到了 AI-Native 阶段，这种组织方式会很快暴露出问题。

大模型应用本质上是由多个能力单元组合起来的：需要检索知识、需要生成文本、需要调用业务接口、需要判断输出质量。如果把每个能力都封装在具体项目内部，第二个项目需要同样能力时，会面临两种选择。要么复制代码和提示词，要么重新写一套相似实现。前者造成“同一技能两种版本”，后者造成重复建设。无论哪种，最后都会导致维护成本失控。

Skills 在这里被定义为一种可独立识别、可描述、可调用、可评测的能力单元。它的粒度介于单条 Prompt 和完整 Agent 之间，是一个“带有运行语义的 AI 能力包”。在 AI-Native SDLC Playbook 中，这种能力包就是组织的最小可复用资产。

从项目交付切换到能力资产，最直接的收益是复用率。两个团队都需要“自然语言转 SQL”，不必各自实现一套。只要有一个已经注册、评测过、有 Owner 的 sql-query-analyzer Skill，另一个团队可以按契约调用。能力变成资产之后，使用量、失败率、成本都可以被统计，也就有了持续优化的数据基础。

1.2 Skill 与 Prompt、Tool、Agent 的边界

很多团队会把 Skill 和提示词模板混为一谈，也会把 Skill 和 Agent 混为一谈。实际工作中，它们处于不同抽象层。

一条 Prompt 只是文本模板，能描述“怎么提问”，但没有运行入口，没有输入输出校验，没有版本和评测。一个 Tool 通常是无状态的函数，能执行某个具体操作，比如查询数据库、发送消息，但它不包含“如何使用模型来完成任务”的描述。一个 Agent 则是决策者，它根据用户目标决定调用哪些 Tool 或 Skill，并处理中间步骤。

Skill 处在中间层，既包含调用模型所需的提示词和参数，也包含执行逻辑、输入输出约束、依赖和评测数据。它可以被 Agent 调度，也可以被另一个 Skill 组合。它的核心目标是：一个团队开发出来的能力，其他团队可以在不了解内部实现的情况下直接使用。

下面用表格对比三者的差异，方便在架构评审时对齐口径。

1.3 组织里至少需要哪几类 Skills

在规划 Skill 体系时，不要一开始就追求数量，先按职责划分几个类别，后续注册和授权会容易很多。

第一类是业务领域类，直接服务业务场景，比如合同关键条款提取、客服回答生成、产品需求摘要。这类 Skill 通常涉及业务数据和领域知识，需要业务团队参与评测。

第二类是工程效能类，服务研发过程本身，比如代码评审总结、单元测试生成、SQL 问题排查、发布说明生成。这类 Skill 最好由平台工程团队先做试点，因为使用场景明确，效果容易度量。

第三类是安全与数据治理类，比如敏感信息识别、越权内容过滤、个人信息脱敏。这类 Skill 不应只被当作辅助工具，而应作为其他 Skill 的上游拦截器使用。

第四类是评测治理类，比如输出质量打分、事实一致性校验、Prompt 回归测试。这类 Skill 用于支撑前面几类的持续迭代，属于平台基础设施。

分类的意义在于权限和目录。业务类 Skill 通常只能被授权团队成员访问；工程效能类可以开放给研发中心；安全类必须由安全团队审核；评测类则需要较高的发布标准。没有分类，Registry 会退化成一个无序的代码仓库。

2. 统一 Skill 内部结构：一份可运行的 Skill 应该包含哪些部分

2.1 为什么先统一结构

Skill 要能被检索、调用、评测和扩展，必须先有统一的内部结构。如果每个团队用不同的字段描述能力，Registry 无法做索引，调度器无法做输入校验，评测系统也无法知道该跑哪些用例。

一个最小 Skill 至少包含六个组成部分：

• 元数据：名称、版本、Owner、描述、标签。
• 输入输出契约：描述调用方需要传入什么，返回什么。
• 运行实现：真实处理逻辑，可能是 Python 函数、API 调用或工作流。
• 依赖声明：第三方库、环境变量、模型名称和版本。
• 评测数据：一组输入和预期结果，用来验证新版本是否退化。
• 说明文档：说明适用场景、不适用场景、典型用法和限制。

缺少任何一部分，短期看起来影响不大，长期都会变成问题。没有版本，升级无法追踪；没有输入输出契约，调用方只能看源码；没有评测，Prompt 改了之后不知道效果是变好还是变坏。

2.2 一份 Skill Manifest 示例

为了让结构可解析，建议用一个skill.yaml文件作为 Skill 的唯一事实来源。下面是一个文档摘要 Skill 的简化示例。

apiVersion: skills.internal/v1 kind: Skill metadata: name: document-summarizer version: v1.4.0 displayName: 文档摘要技能 description: 将长文压缩为指定字数的中文摘要，支持调整阅读对象和语气。 owner: team-ai-platform tags: [summarization, llm, document] spec: input: type: json properties: text: type: string description: 待摘要的正文内容 maxWords: type: integer default: 200 minimum: 10 maximum: 2000 audience: type: string enum: [executive, developer, general] default: general required: [text] output: type: json properties: summary: type: string description: 摘要结果 wordCount: type: integer description: 实际摘要字数 runtime: language: python entrypoint: src/run.py requirements: requirements.txt env: LLM_MODEL: ${LLM_MODEL:-gpt-4o-mini} LLM_API_KEY: ${LLM_API_KEY} llm: temperature: 0.2 max_tokens: 1024 eval: dataset: eval/cases.jsonl metrics: - contains_keyword - length_lte

这个文件解决三个问题。第一，Registry 可以读取metadata.name和metadata.version做索引。第二，调用方可以通过spec.input和spec.output生成校验逻辑，不需要阅读源码。第三，评测系统可以根据spec.eval.dataset找到测试用例，跑完自动判断是否通过。

这里要注意，env中不要出现明文密钥。示例中的${LLM_API_KEY}表示从环境中读取，实际项目建议接入公司的密钥管理系统。

2.3 用 Python 实现一个可运行的 Skill

skill.yaml只是描述，真正的逻辑放在src/run.py。下面是一个最小实现，它演示了 Skill 的标准输入输出契约。

# skills/document-summarizer/src/run.py import json import sys from typing import Dict, Any def validate_input(data: Dict[str, Any]) -> None: if "text" not in data: raise ValueError("missing required field: text") text = data["text"] if not isinstance(text, str) or len(text.strip()) == 0: raise ValueError("text must be a non-empty string") max_words = data.get("maxWords", 200) if not isinstance(max_words, int) or not (10 <= max_words <= 2000): raise ValueError("maxWords must be integer between 10 and 2000") def handler(data: Dict[str, Any]) -> Dict[str, Any]: validate_input(data) text = data["text"] max_words = int(data.get("maxWords", 200)) # 演示分支：极短文本直接返回原文本，实际项目会调用 LLM 网关 if len(text.split()) <= max_words * 0.2: return { "summary": text.strip(), "wordCount": len(text.split()), } # 实际项目中这里应该调用内部 LLM 服务，并把请求 ID 写入日志 preview = text.strip()[: max_words * 5] return { "summary": f"（示例摘要）{preview}", "wordCount": len(preview.split()), } if __name__ == "__main__": raw = sys.stdin.read() payload = json.loads(raw) result = handler(payload) print(json.dumps(result, ensure_ascii=False))

运行方式：

echo '{"text": "这是需要被摘要的长文档内容，实际中会很长。", "maxWords": 30}' | python src/run.py

预期输出：

{"summary": "（示例摘要）这是需要被摘要的长文档内容，实际中会很长。", "wordCount": 10}

这个例子刻意简化了模型调用，重点是让读者看到 Skill 的标准边界：通过标准 JSON 输入执行，返回标准 JSON，异常通过ValueError暴露。真实项目中，handler内部会调用统一模型网关，再把模型返回结果转换成契约中的输出格式。

2.4 输入校验与错误处理是 Skill 的隐形边界

Skill 最容易忽略的部分是错误处理。模型可能超时，LLM 可能返回非 JSON，输入文本可能包含超长内容，用户可能传入敏感数据。如果错误处理不统一，调用方无法判断失败原因。

建议每个 Skill 实现统一的错误输出结构，例如：

{ "error": { "code": "INVALID_INPUT", "message": "maxWords must be integer between 10 and 2000", "requestId": "req_123456" } }

错误码可以分为INVALID_INPUT、LLM_TIMEOUT、LLM_BAD_RESPONSE、DEPENDENCY_ERROR、RATE_LIMITED等。Registry 中可以登记每个 Skill 支持的错误码，这样监控系统能统一聚合失败原因。

这里有一个常见坑：不要在日志里记录完整的用户输入。尤其当 Skill 涉及合同、客服会话、用户资料时，日志全量输出会导致敏感数据泄露。调试阶段可以打印前几十个字符，生产环境应记录输入的长度、哈希和请求 ID。

3. 用 Skill Registry 把零散能力变成可检索的资产

3.1 为什么不能只把 Skill 放在 Git 仓库

Git 仓库解决了版本管理，但没有解决可发现性。一个 Skill 放在skills/document-summarizer目录下，另一个团队不知道它存在时，还是会重新写一个。即使知道，也需要读源码才能判断是否适合自己的场景。

Skill Registry 是一个独立于 Git 仓库的能力目录，它保存每个 Skill 的元数据、索引、授权关系、近期版本和运行状态。

用表格对比 Git 仓库和 Registry：

实际落地时不需要另建一套复杂系统。可以先基于 Git 仓库加一个索引文件，再逐步扩展成服务化 Registry。

3.2 目录结构和命名规范

推荐的目录结构如下。

ai-native-skills/ skills/ document-summarizer/ skill.yaml src/ run.py requirements.txt eval/ cases.jsonl README.md sql-query-analyzer/ skill.yaml src/ run.py requirements.txt eval/ cases.jsonl README.md registry/ lib/ scan.py validate.py

命名规范要尽早定下来。Skill 名称建议使用小写字母和连字符，格式为<domain>-<action>，例如doc-summarizer、sql-analyzer、contract-extractor。

版本规范建议使用vMAJOR.MINOR.PATCH。输入输出契约变化时升MAJOR；新增可选参数、新增能力时升MINOR；只调整 Prompt 措辞或修复异常时升PATCH。

3.3 最小注册流程：扫描、校验、生成索引

注册一个 Skill 不能只靠手动填写 excel 表格。至少需要一条命令，扫描目录，校验skill.yaml，并生成可检索的索引。

下面给出一个最小扫描脚本，它使用 PyYAML 解析 manifest，并检查必填字段。

# registry/lib/scan.py import json import sys from pathlib import Path import yaml REQUIRED_METADATA_FIELDS = ["name", "version", "description", "owner"] REQUIRED_SPEC_FIELDS = ["input", "output", "runtime"] def validate_skill(path: Path) -> list[str]: with path.open("r", encoding="utf-8") as fh: data = yaml.safe_load(fh) errors = [] metadata = data.get("metadata", {}) spec = data.get("spec", {}) for field in REQUIRED_METADATA_FIELDS: if not metadata.get(field): errors.append(f"missing metadata.{field}") for field in REQUIRED_SPEC_FIELDS: if spec.get(field) is None: errors.append(f"missing spec.{field}") version = metadata.get("version", "") if not version.startswith("v"): errors.append("version must start with 'v'") return errors def main() -> None: root = Path(sys.argv[1]) if not root.exists(): print(f"path not found: {root}") raise SystemExit(1) errors_by_skill = {} for manifest in root.rglob("skill.yaml"): errors = validate_skill(manifest) if errors: errors_by_skill[str(manifest)] = errors if errors_by_skill: print(json.dumps(errors_by_skill, ensure_ascii=False, indent=2)) raise SystemExit(1) print("all skills valid") if __name__ == "__main__": main()

使用方式：

python registry/lib/scan.py skills/

输出为all skills valid时，说明所有 Skill 的 manifest 满足最小约束。将这个脚本接入 CI，可以确保每次合并 MR 前，新增或修改的 Skill 不会破坏基础结构。

校验通过后，Registr 可以生成一个index.json，把每个 Skill 的名称、版本、标签、入口、Owner 汇总起来，供内部开发者搜索使用。生产环境建议把这个索引写入数据库，并用 HTTP API 暴露给调用方。

3.4 权限、可见性和审批

Skill 不是所有内容都能公开给全公司。一个涉及支付规则的 Skill 和一个文档摘要 Skill，可见范围显然不同。

建议把 Skill 分成三个级别：

权限还必须做到运行时校验。即使 Skill 被搜索到，调用方如果不在授权列表内，接口也要返回403 FORBIDDEN。权限判断不要只靠前端隐藏，后端 Registry 必须重新校验。

4. 版本、评测与依赖：让 Skill 可以持续演进

4.1 版本策略：语义化版本是底线

AI-Native Skill 和普通代码库一样，需要严格的版本策略。尤其要区分哪些变化是破坏性的。

• 修改spec.input中必填字段，是MAJOR变更。
• 修改输出字段名或类型，是MAJOR变更。
• 新增可选输入参数，是MINOR变更。
• 调整提示词措辞、修复超时处理，是PATCH变更。
• 只修改评测数据，不改变输出契约，可以按PATCH发布。

Skill 的version要同时出现在 manifest 和运行时 API 响应中。调用方如果锁定doc-summarizer@v1.4.0，调度器就必须请求该版本，而不是偷偷使用最新版。

4.2 引入评测数据集：让升级有依据

LLM 应用最特殊的地方在于输出不稳定。同一个 Skill 改了一行提示词，可能在测试集上表现变好，在真实场景却变差。因此，每个 Skill 都应该绑定至少一个评测数据集。

eval/cases.jsonl的每一行表示一个测试用例，结构如下：

{"input": {"text": "人工智能正在改变软件开发方式，尤其是代码生成和测试自动化领域。"}, "expected": {"keyword": "人工智能"}, "metric": "contains_keyword"}

评测脚本按 metric 执行不同判断：

# registry/lib/eval_simple.py import json import sys def run_case(case: dict, runner_result: dict) -> bool: metric = case.get("metric", "contains_keyword") expected = case["expected"] if metric == "contains_keyword": return expected["keyword"] in runner_result.get("summary", "") if metric == "length_lte": return len(runner_result.get("summary", "")) <= expected["max_len"] return False def main() -> None: eval_file = sys.argv[1] runner_output = json.loads(sys.argv[2]) total = 0 passed = 0 with open(eval_file, "r", encoding="utf-8") as fh: for line in fh: line = line.strip() if not line: continue case = json.loads(line) total += 1 if run_case(case, runner_output): passed += 1 print(f"{passed}/{total} passed") if passed < total: raise SystemExit(1) if __name__ == "__main__": main()

评测结果应和版本绑定。一个 Skill 只有在评测通过率不低于上一版时，才允许发布到生产。如果允许少量回退，要在发布单中明确说明原因。

4.3 依赖管理和环境隔离

Skill 不是一段孤立的 Python 函数，它可能依赖第三方库、内部 SDK、模型名称、知识库版本。建议在requirements.txt中锁定依赖，在skill.yaml的runtime.env中声明环境变量。

实践建议：

• 模型名称不要写死在代码里，统一从环境变量读取。
• API Key 使用密钥管理服务注入，不要在 manifest 里出现明文。
• 将 LLM 网关地址作为全局环境变量，避免每个 Skill 维护不同的接入方式。
• 在测试阶段固定模型版本，避免上游模型升级导致输出变化。

4.4 从单一 Skill 组合成 Workflow

当 Skills 越来越多，单个 Skill 不足以完成复杂任务时，可以将多个 Skill 组合成 Workflow。比如“客服工单总结”可以由doc-summarizer、sentiment-analyzer、sensitive-data-masker组合完成。

组合顺序很重要。敏感信息识别应该在最前面，脱敏后再进入摘要和情感分析，否则摘要结果可能包含个人信息。

组合实现时，Workflow 本身也可以被注册为一个 Skill。它的入口是一个 DAG 定义，内部节点指向其他 Skill 的版本号。这样组织既能复用原子能力，又能沉淀更高层的业务能力。

5. 在团队中规模化扩展：试点、Owner 与发布全流程

5.1 先选一个高频场景做试点

很多团队一开始就想搭建“全面 AI-Native 平台”，这个想法很容易导致失败。平台没有真实需求支撑，Skill 数量很少，用户不知道能搜到什么，最终变成一个空壳。

建议先选一个真实且高频的场景，比如“代码评审总结”或“测试用例生成”。确定场景后，按下面顺序推进：

1. 明确业务目标和验收指标。
2. 确定 Skill Owner。
3. 用最小 contract 开发第一版。
4. 接入真实代码库或业务数据，做小范围试用。
5. 记录调用量、失败率、节省时间。

试点阶段不要过度设计。一个 Skill 只要能服务真实场景，并且让另一个团队愿意调用，就比十个未上线的实验性 Skill 更有价值。

5.2 建立 Skill Owner 和评审机制

每个 Skill 必须有 Owner，也就是对这个 Skill 的稳定性负责的人。Owner 的职责包括：

• 确认输入输出契约不被随意破坏。
• 维护评测数据集。
• 关注调用方反馈和错误日志。
• 决定何时发布新版本。

发布评审不必太重。对于 Public 级别 Skill，建议至少经过一次代码评审、一次安全确认、一次评测通过，才能进入生产目录。对于 Private 级别，可以让 Owner 单独决定。

5.3 把发布接入 CI/CD

Skill 的发布过程应该自动化，否则每次升级都靠人工执行脚本，会很容易漏掉评测或校验。

一个通用流水线至少包含以下阶段：

stages: - validate - test - eval - publish validate: stage: validate script: - python registry/lib/scan.py skills/document-summarizer test: stage: test script: - cd skills/document-summarizer - pip install -r requirements.txt - python -m pytest tests/ -q eval: stage: eval script: - echo '{"text": "..."}' | python src/run.py > /tmp/result.json - python ../../registry/lib/eval_simple.py eval/cases.jsonl /tmp/result.json publish: stage: publish script: - python registry/cli publish skills/document-summarizer

这个 YAML 只是结构示意，具体运行环境要结合自己的 CI 平台调整。关键点是每个阶段失败都要阻止发布。评测阶段尤其要保留历史通过率，否则无法判断新版本是否退化。

5.4 可观测性与成本治理

Skill 进入生产后，必须有观测数据支撑后续决策。每条请求建议记录：

• 请求 ID 和调用方。
• Skill 名称和版本。
• 模型名称和输入 Token 量。
• 响应耗时和失败错误码。
• 成本和评测结果。

一个实用的监控面板至少包含四项指标：调用量、成功率、P95 耗时、Token 成本。当某个 Skill 被多个 Agent 共用时，成本会快速增长，必须设定预算阈值。

注意：不要把日志和监控放在发布之后补。Skill 上线第一天就需要能看到调用量和错误码，否则问题只能等用户反馈。

6. 常见问题排查：为什么 Skill 上线后没人用或效果不稳定

6.1 现象：明明注册了，却在搜索里找不到

可能原因：

• 注册脚本没有在 CI 中自动执行，索引仍是旧版本。
• skill.yaml中metadata.tags为空，搜索时匹配不到关键词。
• Skill 级别太高，调用方不在可见范围内。

排查方式：

• 先检查 Registry 索引中是否存在该 Skill。
• 再检查当前用户的权限角色。
• 最后检查搜索服务是否读取了最新索引。

对应解决方式：将scan和索引生成接入发布流水线；给 Skill 补充领域标签；检查权限配置。

6.2 现象：同一个 Skill 在不同环境输出差异大

这是 AI-Native 系统中最高频的问题。可能原因：

• 不同环境使用了不同模型版本。
• temperature在环境变量中被重新覆盖。
• 提示词文件中包含未被版本管理的参数。
• 知识库版本不一致，导致 RAG 检索结果不同。

排查方式：

• 对比两个环境的skill.yaml中的llm配置。
• 查看两个环境的模型网关路由规则。
• 检查输出日志中记录的模型指纹、Prompt 版本。

解决方式：统一模型网关，固定模型版本，将 Prompt 视为代码纳入版本管理，并在日志中输出配置指纹。

6.3 现象：升级后调用方开始报错

可能原因：

• 修改了输出字段名或类型，但没有升级MAJOR版本。
• 调用方没有锁定版本，一直请求最新版。
• 新增必填输入字段，导致旧调用方请求失败。

排查方式：

• 查看调用方请求中的版本号。
• 比对两个版本的spec.input和spec.output。
• 查看发布日志中的变更类型。

解决方式：严格语义化版本；调用方使用版本范围时要设上限；发布MAJOR版本前，通过兼容性测试并通知所有订阅者。

6.4 现象：Skill 返回内容里出现敏感数据

可能原因：

• 输入未经过脱敏处理。
• Prompt 中把完整原文传给了外部模型网关。
• 日志记录保留了完整输入和输出。

排查方式：

• 查看网关请求日志中的字段。
• 检查是否有sensitive-data-masker等治理 Skill 被前置调用。
• 检查输出日志的数据保留策略。

解决方式：把脱敏治理 Skill 放在所有业务 Skill 前；网关层设置敏感字段过滤；日志只保留关键字段长度和哈希。

6.5 排查总表

7. 落地步骤与发布检查清单

7.1 从 0 到 1 的推进顺序

如果团队现在还没有 Skill 体系，建议按下面阶段推进。

这个顺序的关键是把“平台化”放到后面。先有可复用资产，再建设管理资产的基础设施。

7.2 Skill 发布检查清单

在发布或升级一个 Skill 前，建议逐项检查：

• skill.yaml包含名称、版本、描述、Owner。
• 输入输出字段明确，必填字段有语义。
• 错误码覆盖常见失败场景。
• 安全性：没有明文密钥，日志不包含敏感数据。
• 依赖声明完整，环境变量有默认值。
• 评测数据集存在，且通过率不低于上一版。
• 版本号符合语义化版本规则。
• 调用方兼容性已确认，破坏性变更已通知。
• 监控指标已接入，包括调用量、失败率和成本。

7.3 下一步扩展方向

Skill 体系搭建起来后，可以考虑三个扩展方向。

第一，将 RAG 检索能力也封装成 Skill，让知识库版本、分块策略、召回参数都纳入版本管理。这样业务 Skill 可以直接依赖knowledge-retriever@v2.1.0，而不是在内部自行维护检索逻辑。

第二，建立自动评测平台，把人工整理评测集升级为线上回归集。每次 Skill 发布，自动跑一组覆盖边界的用例，并生成效果对比报告。

第三，把 Skill 与组织流程打通。比如新员工入职后通过内部 Skill 目录快速找到“合同审查”能力，而不是看几十个文档。调用方也可以通过反馈按钮标记某次输出质量差，数据回流到评测集。

AI-Native 组织真正能扩展的不是某一个模型，而是围绕 Skills 建立的协作机制。与其等平台彻底成熟后再推行，不如先从一个团队、一个高频场景、一份可运行的skill.yaml开始。后面所有的问题，都会在这个最小闭环里被真实需求逼出来。