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 组合。它的核心目标是一个团队开发出来的能力其他团队可以在不了解内部实现的情况下直接使用。下面用表格对比三者的差异方便在架构评审时对齐口径。维度Tool / 普通函数SkillAgent核心资产代码逻辑代码 Prompt 元数据 评测决策流程 工具编排运行入口函数调用或 API标准输入输出契约任务会话可发现性依赖文档和口头相传通过 Registry 检索依赖内部规划升级方式改代码重新部署版本化 评测后发布策略调整典型规模单点能力跨团队复用能力包复杂任务自动化是否包含评测通常没有必须有可以没有统一评测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 实现一个可运行的 Skillskill.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_asciiFalse))运行方式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 仓库Skill Registry版本管理强基于 Git 或独立存储全文搜索弱只能搜代码按名称、标签、描述检索权限控制仓库级Skill 级可细分运行状态不感知记录调用量、失败率审批流依赖 MR可配置发布审批评测结果不在版本库中统一维护与版本关联实际落地时不需要另建一套复杂系统。可以先基于 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, encodingutf-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(fmissing metadata.{field}) for field in REQUIRED_SPEC_FIELDS: if spec.get(field) is None: errors.append(fmissing 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(fpath 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_asciiFalse, indent2)) 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 分成三个级别级别可见范围审批要求典型场景Public全组织可见可调用Owner 发布文档摘要、通用文本处理Internal指定团队或项目可见Owner 平台审核业务领域技能、收费模型Private仅 Owner 和指定人员可见Owner 审批安全规则、未对外能力权限还必须做到运行时校验。即使 Skill 被搜索到调用方如果不在授权列表内接口也要返回403 FORBIDDEN。权限判断不要只靠前端隐藏后端 Registry 必须重新校验。4. 版本、评测与依赖让 Skill 可以持续演进4.1 版本策略语义化版本是底线AI-Native Skill 和普通代码库一样需要严格的版本策略。尤其要区分哪些变化是破坏性的。修改spec.input中必填字段是MAJOR变更。修改输出字段名或类型是MAJOR变更。新增可选输入参数是MINOR变更。调整提示词措辞、修复超时处理是PATCH变更。只修改评测数据不改变输出契约可以按PATCH发布。Skill 的version要同时出现在 manifest 和运行时 API 响应中。调用方如果锁定doc-summarizerv1.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, encodingutf-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 数量很少用户不知道能搜到什么最终变成一个空壳。建议先选一个真实且高频的场景比如“代码评审总结”或“测试用例生成”。确定场景后按下面顺序推进明确业务目标和验收指标。确定 Skill Owner。用最小 contract 开发第一版。接入真实代码库或业务数据做小范围试用。记录调用量、失败率、节省时间。试点阶段不要过度设计。一个 Skill 只要能服务真实场景并且让另一个团队愿意调用就比十个未上线的实验性 Skill 更有价值。5.2 建立 Skill Owner 和评审机制每个 Skill 必须有 Owner也就是对这个 Skill 的稳定性负责的人。Owner 的职责包括确认输入输出契约不被随意破坏。维护评测数据集。关注调用方反馈和错误日志。决定何时发布新版本。发布评审不必太重。对于 Public 级别 Skill建议至少经过一次代码评审、一次安全确认、一次评测通过才能进入生产目录。对于 Private 级别可以让 Owner 单独决定。5.3 把发布接入 CI/CDSkill 的发布过程应该自动化否则每次升级都靠人工执行脚本会很容易漏掉评测或校验。一个通用流水线至少包含以下阶段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 排查总表问题现象可能原因检查重点处理建议搜索不到索引未更新或权限不可见Registry 索引、角色权限接入 CI 自动索引补充标签环境输出差异大模型版本或配置不一致环境变量、模型网关路由固定模型版本统一网关升级后报错破坏性变更未升 Major输入输出契约 diff严格执行语义化版本敏感数据泄露未脱敏或日志全量记录日志、输入链路前置脱敏 Skill限制日志字段7. 落地步骤与发布检查清单7.1 从 0 到 1 的推进顺序如果团队现在还没有 Skill 体系建议按下面阶段推进。阶段核心动作产出检查点第一阶段选定一个高频场景写第一份 skill.yaml可运行的 Skill 原型能通过 registry scan 校验第二阶段接入真实数据或代码补齐评测集评测报告通过率稳定成本可控第三阶段建立最小 Registry生成索引能力目录另一个团队能搜索并调用第四阶段接入 CI/CD 和监控自动发布流水线发布可回滚错误可追踪第五阶段开放多团队共建多 Owner 协作机制新增 Skill 有明确评审流程这个顺序的关键是把“平台化”放到后面。先有可复用资产再建设管理资产的基础设施。7.2 Skill 发布检查清单在发布或升级一个 Skill 前建议逐项检查skill.yaml包含名称、版本、描述、Owner。输入输出字段明确必填字段有语义。错误码覆盖常见失败场景。安全性没有明文密钥日志不包含敏感数据。依赖声明完整环境变量有默认值。评测数据集存在且通过率不低于上一版。版本号符合语义化版本规则。调用方兼容性已确认破坏性变更已通知。监控指标已接入包括调用量、失败率和成本。7.3 下一步扩展方向Skill 体系搭建起来后可以考虑三个扩展方向。第一将 RAG 检索能力也封装成 Skill让知识库版本、分块策略、召回参数都纳入版本管理。这样业务 Skill 可以直接依赖knowledge-retrieverv2.1.0而不是在内部自行维护检索逻辑。第二建立自动评测平台把人工整理评测集升级为线上回归集。每次 Skill 发布自动跑一组覆盖边界的用例并生成效果对比报告。第三把 Skill 与组织流程打通。比如新员工入职后通过内部 Skill 目录快速找到“合同审查”能力而不是看几十个文档。调用方也可以通过反馈按钮标记某次输出质量差数据回流到评测集。AI-Native 组织真正能扩展的不是某一个模型而是围绕 Skills 建立的协作机制。与其等平台彻底成熟后再推行不如先从一个团队、一个高频场景、一份可运行的skill.yaml开始。后面所有的问题都会在这个最小闭环里被真实需求逼出来。