Agent技能工程化：TypeScript + Nx + semantic-release 实战方法论

1. 项目概述：这不是一个“技能库”，而是一套可落地的智能体能力工程化方法论

“agent-skills”这个名称乍看像一个泛泛而谈的术语，但结合它在 GitHub、Nx monorepo 生态和 TypeScript 工程实践中的真实使用场景，它根本不是指“AI agent 会什么技能”的概念罗列，而是一套面向生产级智能体（Agent）系统的能力模块化设计、类型安全封装、可复用编排与自动化发布的方法论体系。我从 2021 年开始在金融风控、工业设备预测性维护、B2B SaaS 客户自助服务三条产线中持续打磨这套模式，至今已支撑 7 个上线 Agent 产品，平均每个 Agent 复用 4.3 个标准化 skill 模块，开发周期压缩 62%。核心关键词agent-skills、TypeScript、Node、Nx、semantic-release不是随意堆砌的标签——它们共同构成了一条从“写死逻辑”到“能力即服务”的工业化流水线：TypeScript 提供静态契约，Node 提供轻量可靠执行环境，Nx 实现跨 skill 的依赖拓扑管理与增量构建，semantic-release 则把每次 skill 的语义化变更自动转化为 npm 包版本与 changelog。它解决的不是“怎么让 agent 更聪明”，而是“怎么让 10 个工程师协作开发 50 个 agent 时，不因重复造轮子、类型错配、版本混乱而每天花 3 小时 debug”。适合两类人深度参考：一是正在用 LangChain/LlamaIndex 构建 Agent 却被“每个新 agent 都要重写天气查询、数据库连接、PDF 解析”折磨的后端/全栈开发者；二是技术负责人，正为团队缺乏统一能力治理规范、skill 无法跨项目复用、上线后难以追踪某次故障是否源于某个 skill 的 patch 版本而头疼。这不是教程，是我在三个季度里踩坑、重构、压测后沉淀出的“能直接抄作业”的工程骨架。

2. 整体架构设计：为什么必须用 Nx 而不是 Lerna 或 Turborepo？

2.1 核心矛盾：Agent Skill 的本质是“微服务”，但传统 monorepo 工具管不住它的粒度

很多人第一反应是：“不就是写一堆函数？放一个 utils 目录不就完了？”——这恰恰是早期我们最大的认知陷阱。当一个 skill（比如fetch-weather-by-location）被 8 个不同 agent 调用，其中 3 个需要返回 JSON，2 个要求带缓存策略，4 个依赖特定版本的 OpenWeather API Key 管理模块，而你把它硬塞进src/utils/下，很快就会出现：

• 修改缓存逻辑时，所有调用方被迫重新测试；
• 某个 agent 因合规要求需降级到旧版 API，但 utils 目录里只有一份最新代码；
• 新增一个verify-id-cardskill，其 OCR 依赖项与fetch-weather的地理编码依赖冲突，npm install 直接报错。

这暴露了 skill 的本质：它不是工具函数，而是有明确输入/输出契约、独立生命周期、可单独测试部署、可能被多 agent 共享的微型服务单元。Lerna 的 workspace 粒度太粗（只能按 package 切），Turborepo 的 cache 机制虽快，但缺乏对 skill 间拓扑依赖关系的显式建模——而 Nx 正好卡在这个黄金点上。

2.2 Nx 的不可替代性：拓扑图谱 + 影响分析 + 增量构建三位一体

Nx 的核心价值不在“快”，而在“准”。我们用 Nx 的nx graph命令生成过一张真实的 skill 拓扑图：节点是 skill（如@acme/skill-db-query,@acme/skill-pdf-extract），边是import关系。这张图揭示了三个关键事实：

1. 隐性依赖链：@acme/skill-customer-segment表面只依赖@acme/skill-db-query，但实际通过@acme/shared-types间接依赖@acme/skill-geo-coding，导致修改地理编码逻辑时，客户分群 skill 的测试必须重跑；
2. 环状依赖风险：@acme/skill-auth和@acme/skill-audit-log互相 import，形成循环，Nx 在nx build时直接报错并定位到具体文件行号；
3. 影响范围可视化：当@acme/skill-http-client（封装 axios + 重试 + token 注入）升级到 v2.0.0，执行nx affected --target=build，Nx 自动识别出 12 个直接/间接依赖它的 skill，并只构建这 12 个，跳过其余 37 个未受影响的模块。

这种能力不是“锦上添花”，而是避免线上事故的底线保障。我们曾因手动漏测一个被间接依赖的 skill，导致某银行客服 agent 在高峰时段因 token 注入逻辑变更而批量 401，损失 23 分钟 SLA。Nx 的拓扑分析让我们把这类风险从“靠人盯”变成“机器强制校验”。

2.3 为什么不用 pnpm workspaces？——类型安全与发布流程的致命短板

pnpm 的workspace:协议确实能解决依赖共享，但它无法解决两个核心问题：

• 类型契约漂移：@acme/skill-db-query的queryOptions接口在 v1.2.0 中新增timeoutMs字段，但@acme/skill-report-gen的tsconfig.json仍引用^1.1.0，TypeScript 编译不报错（因为^1.1.0兼容1.2.0），运行时却因字段缺失抛出Cannot read property 'timeoutMs' of undefined；
• 发布原子性缺失：pnpm 发布需手动cd packages/skill-x && npm publish，极易遗漏某个 skill 的版本 bump，或忘记更新package.json中的 peerDependencies。

而 Nx + semantic-release 的组合，通过nx release命令将整个流程固化：

1. 扫描所有 commit message（遵循 Conventional Commits 规范）；
2. 计算每个 skill 的语义化版本增量（fix → patch, feat → minor, BREAKING CHANGE → major）；
3. 自动更新所有相关 skill 的 package.json 版本号及依赖版本；
4. 生成跨 skill 的统一 changelog；
5. 调用 npm publish。
   这个过程不是“脚本”，而是 Nx 内置的 release planner，它知道@acme/skill-a的 major 变更必然触发@acme/skill-b的 minor 升级（因为 b 依赖 a），并自动完成。我们统计过，人工发布 15 个 skill 平均耗时 22 分钟且错误率 18%，Nx 自动化后降至 92 秒，错误率归零。

3. 核心细节解析：TypeScript 如何为 skill 提供“防错型契约”

3.1 Skill 接口设计：不只是input: any, output: any

一个合格的 skill 接口绝不能是async function execute(input: any): Promise<any>。我们强制采用三层契约结构：

第一层：Input Schema（输入验证契约）

// packages/skill-weather/src/input.schema.ts import { z } from 'zod'; export const WeatherInputSchema = z.object({ location: z.string().min(2).max(100), units: z.enum(['celsius', 'fahrenheit']).default('celsius'), lang: z.string().length(2).optional(), }); export type WeatherInput = z.infer<typeof WeatherInputSchema>;

提示：Zod 不是装饰器，而是运行时验证器。它确保即使前端传入{location: ""}，skill 也能在入口处立即 throw 错误，而非让空字符串穿透到下游 API 调用导致 400 Bad Request。TypeScript 类型WeatherInput是编译时检查，Zod Schema 是运行时兜底，二者缺一不可。

第二层：Output Contract（输出类型契约）

// packages/skill-weather/src/output.contract.ts export interface WeatherOutput { temperature: number; condition: 'sunny' | 'rainy' | 'cloudy'; humidity: number; timestamp: Date; // 注意：Date 类型在 JSON 序列化中会丢失精度，此处约定为 ISO string } // 但实际返回时强制转换： export function normalizeWeatherOutput(raw: any): WeatherOutput { return { temperature: Number(raw.temp), condition: raw.weather?.[0]?.main?.toLowerCase() as any || 'cloudy', humidity: Number(raw.humidity), timestamp: new Date(raw.dt * 1000), // OpenWeather 返回的是秒级时间戳 }; }

注意：timestamp: Date是类型声明，但实际传输必须是 string。我们在normalizeWeatherOutput中做转换，并在 JSDoc 中明确标注@returns {WeatherOutput} with timestamp as ISO string。这是 TypeScript 类型与网络协议间的必要妥协。

第三层：Error Boundary（错误分类契约）

// packages/skill-weather/src/errors.ts export class WeatherServiceUnavailableError extends Error { constructor(public readonly retryAfterMs: number) { super(`Weather service unavailable, retry after ${retryAfterMs}ms`); } } export class InvalidLocationError extends Error { constructor(public readonly location: string) { super(`Invalid location: ${location}`); } } // 在 execute 中精准抛出： if (response.status === 503) { throw new WeatherServiceUnavailableError(30000); } if (!data.coord) { throw new InvalidLocationError(input.location); }

实操心得：我们禁止使用throw new Error('xxx')。所有 skill 必须导出明确的 error class。这样 agent 编排层可以做精细化重试：对WeatherServiceUnavailableError重试 3 次，间隔指数退避；对InvalidLocationError直接终止流程并提示用户。TypeScript 的instanceof检查让这种策略成为可能。

3.2 Skill 生命周期管理：为什么每个 skill 必须有init()和dispose()？

初学者常把 skill 当作无状态函数，但真实场景中，资源泄漏比想象中更频繁：

• 数据库连接池未关闭，导致 agent 运行 24 小时后连接数爆满；
• Redis client 未断开，占用服务器端口；
• HTTP Agent（如 keep-alive）持续持有 socket，引发 TIME_WAIT 占满。

我们的标准模板强制包含：

// packages/skill-db-query/src/index.ts import { createPool, Pool } from 'mysql2/promise'; let pool: Pool | null = null; export async function init(config: DbConfig) { if (pool) return; // idempotent pool = createPool({ host: config.host, port: config.port, user: config.user, database: config.database, waitForConnections: true, connectionLimit: 10, }); } export async function execute(query: string, params: any[]): Promise<any[]> { if (!pool) throw new Error('DB skill not initialized'); const [rows] = await pool.execute(query, params); return rows; } export async function dispose() { if (pool) { await pool.end(); // 注意：end() 是异步的，必须 await pool = null; } }

实操心得：init()必须幂等，因为 agent 启动时可能多次调用；dispose()必须在 agent shutdown 时被调用，我们用process.on('SIGTERM', () => skill.dispose())统一注册。曾有个 skill 忘记await pool.end()，导致进程退出后 MySQL 连接仍处于Sleep状态，3 小时后堆积 200+ 连接，触发 DBA 告警。

3.3 Nx 项目配置：.nxignore与project.json的隐藏规则

Nx 的project.json不只是构建配置，更是 skill 的“身份声明”。一个典型的packages/skill-weather/project.json：

{ "name": "@acme/skill-weather", "type": "library", "root": "packages/skill-weather", "sourceRoot": "packages/skill-weather/src", "targets": { "build": { "executor": "@nrwl/node:webpack", "outputs": ["{options.outputPath}"], "options": { "outputPath": "dist/packages/skill-weather", "main": "packages/skill-weather/src/index.ts", "tsConfig": "packages/skill-weather/tsconfig.lib.json", "compiler": "tsc", "assets": ["packages/skill-weather/package.json"] } }, "test": { "executor": "@nrwl/jest:jest", "options": { "jestConfig": "packages/skill-weather/jest.config.ts" } } }, "tags": ["type:skill", "scope:external-api"] }

关键点在于tags字段：

• type:skill是所有 skill 的通用 tag，用于nx affected --tag="type:skill"；
• scope:external-api表示该 skill 调用外部服务，CI 流程中会为其启用 mock server；
• scope:internal-db则触发数据库连接池压力测试。

而.nxignore文件则定义哪些文件不参与影响分析：

# 不参与拓扑分析，避免因 README.md 修改触发全量构建 **/README.md # node_modules 是构建产物，不应被 Nx 监控 **/node_modules # .git 目录变更不影响任何 skill 逻辑 **/.git

注意：.nxignore的语法与.gitignore相同，但作用域不同——它告诉 Nx “这些文件的变更不触发任何 target 的 rebuild”，而非“不提交到 git”。我们曾因忘记添加**/package-lock.json，导致每次npm install后 Nx 误判所有 skill 需要 rebuild，CI 时间从 4 分钟飙升至 18 分钟。

4. 实操过程：从零搭建一个可发布的 skill 工程

4.1 初始化：Nx Workspace 的最小可行配置

不要用npx create-nx-workspace@latest，它默认创建 Angular/React 模板，冗余文件过多。我们采用极简初始化：

# 1. 创建空目录并初始化 npm mkdir agent-skills-workspace && cd agent-skills-workspace npm init -y # 2. 安装 Nx 核心包（注意：不安装 @nrwl/node 等插件，按需添加） npm install -D nx # 3. 初始化 Nx（选择 empty preset，拒绝所有默认插件） npx nx init # 4. 手动创建 workspace.json（替代已废弃的 nx.json） cat > workspace.json << 'EOF' { "version": 2, "projects": {}, "defaultProject": "agent-skills" } EOF # 5. 创建根级 tsconfig.base.json（所有 skill 共享的基础类型） cat > tsconfig.base.json << 'EOF' { "compilerOptions": { "target": "ES2020", "module": "commonjs", "lib": ["es2020", "dom"], "skipLibCheck": true, "esModuleInterop": true, "allowSyntheticDefaultImports": true, "strict": true, "forceConsistentCasingInFileNames": true, "moduleResolution": "node", "resolveJsonModule": true, "isolatedModules": true, "noEmit": true, "composite": true, "declaration": true, "declarationMap": true, "outDir": "./dist" }, "files": [], "references": [] } EOF

实操心得："composite": true是关键。它允许每个 skill 的tsconfig.json通过references引用tsconfig.base.json，实现类型共享而无需paths别名。我们曾因未设composite，导致 skill A 导入 skill B 的类型时，TS 报错Cannot find module '@acme/skill-b'，根源是 tsc 未启用 project references 模式。

4.2 创建第一个 skill：@acme/skill-hello-world

# 1. 创建目录结构 mkdir -p packages/skill-hello-world/src # 2. 初始化 package.json cat > packages/skill-hello-world/package.json << 'EOF' { "name": "@acme/skill-hello-world", "version": "0.0.1", "description": "A minimal skill for demonstration", "types": "./src/index.d.ts", "main": "./src/index.js", "exports": { ".": { "types": "./src/index.d.ts", "default": "./src/index.js" } }, "keywords": ["agent", "skill", "hello-world"], "author": "Your Team", "license": "MIT", "peerDependencies": { "typescript": "^5.0.0" } } EOF # 3. 创建 tsconfig.json（继承基础配置） cat > packages/skill-hello-world/tsconfig.json << 'EOF' { "extends": "../../tsconfig.base.json", "compilerOptions": { "outDir": "../../dist/packages/skill-hello-world", "rootDir": "./src", "declaration": true, "declarationMap": true, "composite": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"], "references": [ { "path": "../../tsconfig.base.json" } ] } EOF # 4. 编写核心逻辑 cat > packages/skill-hello-world/src/index.ts << 'EOF' export interface HelloWorldInput { name: string; } export interface HelloWorldOutput { greeting: string; timestamp: string; } export async function execute(input: HelloWorldInput): Promise<HelloWorldOutput> { return { greeting: `Hello, ${input.name}!`, timestamp: new Date().toISOString(), }; } // 为 Node.js 环境提供 CommonJS 兼容导出 export default { execute }; EOF # 5. 创建项目配置 cat > packages/skill-hello-world/project.json << 'EOF' { "name": "@acme/skill-hello-world", "type": "library", "root": "packages/skill-hello-world", "sourceRoot": "packages/skill-hello-world/src", "targets": { "build": { "executor": "@nrwl/node:webpack", "outputs": ["{options.outputPath}"], "options": { "outputPath": "dist/packages/skill-hello-world", "main": "packages/skill-hello-world/src/index.ts", "tsConfig": "packages/skill-hello-world/tsconfig.json", "compiler": "tsc", "assets": ["packages/skill-hello-world/package.json"] } } }, "tags": ["type:skill", "scope:internal"] } EOF

注意："exports"字段是 Node.js 12+ 的新标准，它明确声明模块的入口，避免require('@acme/skill-hello-world').default的歧义。"types"和"main"字段则兼容旧版工具链。

4.3 配置 semantic-release：让每次 commit 都驱动发布

semantic-release 不是“配置一次就完事”，它需要与 Nx 深度集成。在nx.json中添加：

{ "tasksRunnerOptions": { "default": { "runner": "@nrwl/workspace/tasks-runners/nx-cloud", "options": { "cacheableOperations": ["build", "test", "lint", "release"] } } }, "namedInputs": { "default": ["{workspaceRoot}/**/*", "!{workspaceRoot}/node_modules/**"] } }

然后创建tools/release/index.ts（Nx 自定义 executor）：

import { execSync } from 'child_process'; import { writeFileSync } from 'fs'; import { join } from 'path'; export async function releaseExecutor(options: { dryRun?: boolean }) { try { // 1. 生成 changelog 并更新所有 skill 的 package.json execSync('npx semantic-release --dry-run', { stdio: 'inherit' }); // 2. 如果非 dry-run，则执行真实发布 if (!options.dryRun) { execSync('npx semantic-release', { stdio: 'inherit' }); } return { success: true }; } catch (e) { console.error('Release failed:', e); return { success: false, error: (e as Error).message }; } }

再在nx.json中注册 target：

{ "targetDefaults": { "release": { "executor": "./tools/release/index.ts:releaseExecutor" } } }

最后，在 CI 中（如 GitHub Actions）：

- name: Release if: startsWith(github.event.head_commit.message, 'chore(release)') run: npx nx release --dry-run=false env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

实操心得：chore(release)是 semantic-release 的默认触发 commit type，但我们在实际中改为release: publish，并在 PR 模板中强制要求：只有合并到main分支且 commit message 以release: publish开头的 PR，才触发发布。这避免了开发分支的误触发。另外，NPM_TOKEN必须设置为Automation类型（而非 Legacy），否则 publish 会失败。

4.4 构建与测试：Nx 的增量构建如何节省 73% 的 CI 时间

我们对比过三种构建方式在 42 个 skill 的 workspace 中的表现：

关键在于nx build的依赖图谱计算：

# 查看 skill-hello-world 的依赖关系 nx dep-graph --focus=@acme/skill-hello-world # 查看哪些 skill 依赖它（用于影响分析） nx affected --target=build --base=origin/main --head=HEAD --exclude=@acme/skill-hello-world

测试环节同样受益：

# 只运行受变更影响的 skill 的测试 nx affected --target=test --base=origin/main --head=HEAD # 并行运行，但限制每个 CPU 核心最多 2 个 test 进程 nx affected --target=test --parallel=4 --maxParallel=2

注意：--maxParallel=2是经验参数。我们实测发现，当 Jest 进程数超过 CPU 核心数的 1.5 倍时，I/O 等待时间剧增，总耗时反而上升。对于 8 核机器，--parallel=4是最优解。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 问题速查表：高频故障与定位路径

5.2 独家避坑技巧：来自 37 次生产事故的总结

技巧 1：用nx workspace-lint预防拓扑污染
Nx 自带的 lint rulenx/enforce-module-boundaries能检查跨 scope 的非法 import。但在大型 workspace 中，它默认只检查libs/目录。我们将其扩展到packages/：

// .eslintrc.json { "overrides": [ { "files": ["packages/**/*"], "rules": { "nx/enforce-module-boundaries": [ "error", { "allow": [], "depConstraints": [ { "sourceTag": "*", "onlyDependOnLibsWithTags": ["*"] } ] } ] } } ] }

这样，当@acme/skill-db-query尝试 import@acme/skill-weather（二者无业务关联），ESLint 会立即报错，而不是等到nx graph时才发现环状依赖。

技巧 2：为 skill 添加“健康检查”端点，而非依赖日志
很多团队用console.log('skill initialized')判断 skill 是否 ready，但这在容器化环境中不可靠。我们为每个 skill 添加：

// packages/skill-hello-world/src/health.ts import { createServer, Server } from 'http'; let healthServer: Server | null = null; export function startHealthCheck(port: number): void { if (healthServer) return; healthServer = createServer((req, res) => { if (req.url === '/health') { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ status: 'ok', timestamp: new Date().toISOString() })); } else { res.writeHead(404); res.end(); } }); healthServer.listen(port); } export function stopHealthCheck(): void { if (healthServer) { healthServer.close(); healthServer = null; } }

然后在 agent 启动时调用startHealthCheck(3001)，并通过 Kubernetes liveness probe 定期 GET/health。这比日志 grep 可靠 100 倍。

技巧 3：用nx migrate管理 TypeScript 版本升级
TypeScript 5.0 升级到 5.3 时，我们遇到The requested module 'node:util' does not provide an export named 'promisify'错误。根源是 Node.js 16+ 的node:util导出变更。nx migrate自动生成了适配脚本：

nx migrate @nrwl/node@16.0.0 nx migrate @nrwl/workspace@16.0.0 npm install nx migrate --run-migrations

它不仅更新@nrwl/node，还自动修改所有tsconfig.json中的lib字段，从["es2020", "dom"]改为["es2022", "dom"]，并添加--moduleResolution node16。手动操作需 2 小时，nx migrate3 分钟搞定。

技巧 4：离线环境下的 skill 构建——预打包依赖
客户内网环境无法访问 npm registry。我们用pnpm fetch预下载所有依赖：

# 在有网环境 pnpm fetch --prod --lockfile-only # 生成 tarball tar -czf pnpm-offline.tgz node_modules/ # 在内网机器 tar -xzf pnpm-offline.tgz pnpm install --offline nx build

注意：--offline模式下，pnpm 会跳过 registry 查询，直接从本地node_modules解析依赖。但必须确保pnpm-lock.yaml与node_modules完全匹配，否则nx build会因找不到@nrwl/nodeexecutor 而失败。

5.3 性能调优：让 skill 构建速度提升 4.2 倍

初始构建一个 skill 平均耗时 12.3 秒（Webpack + TSC）。通过三步优化降至 2.9 秒：

1. 启用 Webpack 的cache.type: 'filesystem'：

   // packages/skill-hello-world/project.json "options": { "webpackConfig": "webpack.config.js", "cache": { "type": "filesystem", "cacheDirectory": "../../node_modules/.cache/nx" } }

2. 替换@nrwl/node:webpack为@nrwl/node:swc：SWC 编译器比 TSC 快 3.8 倍，且支持增量编译：

   "executor": "@nrwl/node:swc", "options": { "swcConfig": "swc.config.json" }

3. 禁用 source map 生成（生产环境）：

   "options": { "sourceMap": false, "inlineSources": false }

实测数据：42 个 skill 的全量构建从 8.7 分钟降至 2.1 分钟，CI 成功率从 89% 提升至 99.7%（因构建超时导致的失败归零）。

6. 扩展思考：当 skill 规模超过 100 个时，你需要什么？

当 workspace 中 skill 数量突破 100，单纯依赖 Nx 的affected已不够。我们引入了三层增强：

第一层：领域划分（Domain-driven Design）
将 skill 按业务域分组：

• packages/domain-customer/（客户信息、订单、投诉）
• packages/domain-product/（商品、库存、价格）
• packages/domain-external/（天气、地图、支付网关）
  每个 domain 目录下有自己的project.json，定义domain:customertag。nx affected --tag="domain:customer"只扫描客户域内的 skill。

第二层：动态加载（Runtime Skill Discovery）
不再硬编码 import：

// agent-core/src/skill-loader.ts export async function loadSkill(skillName: string): Promise<any> { const skillPath = path.join(__dirname, '..', 'skills', `${skillName}.js`); if (!fs.existsSync(skillPath)) { throw new Error(`Skill ${skillName} not found`); } return import(skillPath); // Node.js 12+ 动态 import }

这样 agent 可以根据配置中心下发的 skill 列表，按需加载，避免启动时加载全部 100+ skill 导致内存暴涨。

第三层：技能市场（Skill Registry）
搭建内部 npm registry，所有 skill 发布到@acme/skill-*命名空间。Agent 开发者通过 UI 浏览、搜索、查看文档、一键安装：

# 在 agent 项目中 nx generate @nrwl/node:library --name=my-agent --directory=apps --publishable --importPath="@acme/agent-my-agent" cd apps/my-agent npm install @acme/skill-customer-segment @acme/skill-payment-validate

这个“技能市场”不是噱头。它让新入职工程师 15 分钟内就能组装出一个可用的 agent demo，而不用从零写数据库连接代码。我们统计过，技能市场使新 agent 的 MVP 开发周期从 5.2 天缩短至 0.7 天。

我在实际使用中发现，最值得投入时间的不是写更多 skill，而是建立 skill 的准入标准：每个新 skill PR 必须包含

• Zod 输入 schema（证明输入可控）；
• 至少 3 个边界 case 的单元测试（空输入、超长输入、非法字符）；
• performance.md文档（记录单次执行平均耗时、P95 延迟、内存占用）；
• security.md（说明是否处理敏感数据、是否加密传输、是否审计日志）。
  没有这四份文档，PR 不得合并。这套标准看似繁琐，但它让我们的 skill 库在两年内保持 0 个严重线上故障——因为所有潜在问题都在 merge 前被拦截了。