写了 10 个 Agent Skill 后，我把 300 行重复代码压到了 30 行

最近半年陆陆续续写了 10 来个 Agent Skill，踩了不少工程上的坑。

写到第 3 个 Agent Skill 的时候，我发现已经复制了三套 HTTP 封装。Cookie 鉴权的、Bearer Token 的、带网络异常兜底的——三份 http.ts，哪天鉴权方式一切换，同一段逻辑要改 3 次。

这还只是 HTTP。命令路由、参数校验、错误处理、SKILL.md 校验、产物同步——写到第 5 个 Skill 时，这些和业务无关的工程问题，已经占了我不少精力。

把这类重复劳动收敛成一套工具链，就是 skill-kits 想做的事情。

先看它实际解决了什么：

指标	重构前：手搓 Skill	重构后：基于 skill-kits
新建一个 Skill	每次重做一遍工程决策	pnpm new <name> 一行命令
HTTP / 错误处理等工具	每个 Skill 复制一份	从 runtime import，零依赖内联
代码改动同步到 Agent	cp -r / 手动同步	pnpm dev 一条命令 watch + 同步
SKILL.md 质量检验	全靠肉眼 review	pnpm build 自动检查

一、一段 fetch，在 3 个 Skill 里维护了 3 份

写到第 3 个 Skill 的时候，我发现已经复制了三套 HTTP 封装。

// skill1/scripts/http.ts —— Cookie 鉴权 + 错误详情提取
async function request<T>(
  method: "GET" | "POST",
  domain: string,
  path: string,
  token: string,
  options?: { params?: Record<string, string>; body?: unknown },
) {
  const url = new URL(`${domain}/gms_api${path}`);
  if (options?.params) {
    Object.entries(options.params).forEach(([k, v]) => {
      url.searchParams.set(k, v);
    });
  }

  const res = await fetch(url.toString(), {
    method,
    headers: {
      "Content-Type": "application/json",
      Cookie: `x-token=${token}`,
    },
    body: options?.body ? JSON.stringify(options.body) : undefined,
  });

  if (!res.ok) {
    const detail = await res.text().catch(() => "");
    throw new Error(`HTTP ${res.status}: ${res.statusText}\n${detail}`);
  }

  return res.json() as Promise<ApiResponse<T>>;
}

// skill2/scripts/http.ts —— Bearer Token + 网络异常兜底 + 响应解析容错
async function postJson<T>(url: string, body: unknown, token?: string) {
  let response: Response;

  try {
    response = await fetch(url, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        ...(token ? { authorization: `Bearer ${token}` } : {}),
      },
      body: JSON.stringify(body),
    });
  } catch (error) {
    return {
      httpOk: false,
      status: 0,
      statusText: `NetworkError: ${error instanceof Error ? error.message : String(error)}`,
      data: null,
    };
  }

  const raw = await response.text();
  let data: unknown = null;
  try {
    data = JSON.parse(raw);
  } catch {
    data = { raw };
  }

  return { httpOk: response.ok, status: response.status, data: data as T };
}

// skill3/scripts/http.ts —— 又是另一套（省略）

三个 Skill，三份 http.ts，一个变动可能需要把同一段逻辑修改 3 次，这无疑抬高了维护成本。

所以我在 skill-kits 的 Runtime 里收了一层薄的 fetch 封装。不做大而全的 HttpClient，只解决"少写一点 fetch 样板"这件事：

import { httpGet, HttpError } from "skill-kits/runtime";

const res = await httpGet<UserInfo>("https://api.example.com/me", {
  headers: { authorization: `Bearer ${token}` },
  query: { fields: "id,name" },
  timeoutMs: 10_000,
});

if (!res.ok) {
  throw new HttpError(res.status, url, res.statusText);
}

剩下那层跟业务强相关的封装，就交给各个 Skill 自己包。

HTTP 之外，错误处理也是重灾区。之前每个 Skill 各自 throw new Error("xxx")，排查时只能靠猜 message。我把常见错误收进了统一的 code 里：

类	code	典型场景
UserInputError	USER_INPUT_ERROR	参数缺失 / 格式错误
AuthError	AUTH_ERROR	Token 过期 / 权限不足
HttpError	HTTP_ERROR	上游 HTTP 非 2xx
BusinessApiError	BIZ_<code>	HTTP 200 但业务 code ≠ 0

几个典型用法：

import { SkillError, UserInputError, BusinessApiError } from "skill-kits/runtime";

// UserInputError：参数校验失败
throw new UserInputError("activityId 不能为空", { field: "activityId" });
// stderr → {"ok":false,"code":"USER_INPUT_ERROR","error":"activityId 不能为空","details":{"field":"activityId"}}

// 自定义 BusinessApiError 错误
throw new BusinessApiError(-10000, "token 过期", {
  hintMap: { [-10000]: "请重新登录", [-14]: "记录不存在" },
});
// stderr → {"ok":false,"code":"BIZ_-10000","error":"[code=-10000] token 过期（请重新登录）"}

// 自定义业务错误：继承 SkillError，code 自由命名
class RateLimitError extends SkillError {
  constructor(retryAfterSec?: number) {
    super("RATE_LIMIT", "请求过于频繁", { retryAfterSec });
  }
}
throw new RateLimitError(30);
// stderr → {"ok":false,"code":"RATE_LIMIT","error":"请求过于频繁","details":{"retryAfterSec":30}}

这样无论是人工排查，还是 LLM 后续做分支处理，都无需再从冗长的 message 中猜测错误含义。

二、7 个子命令，main.ts 写了 250 行 parseArgs + switch

我在写营销活动管理 Skill 的时候，7 个子命令，main.ts 基本就是一大坨 parseArgs + switch + usage + 参数校验。

// ❌ 手搓版：parseArgs + switch，约 250 行
function parseArgs(): CliOptions {
  const args = process.argv.slice(2);
  const opts: Partial<CliOptions> = {};

  for (let i = 1; i < args.length; i++) {
    switch (args[i]) {
      case "--domain":
        opts.domain = args[++i];
        break;
      case "--app-id":
        opts.appId = args[++i];
        break;
      case "--token":
        opts.token = args[++i];
        break;
      case "--activity-id":
        opts.activityId = args[++i];
        break;
      case "--body":
        opts.body = args[++i];
        break;
      // ... 还有十几个 case
    }
  }

  if (!opts.domain) {
    console.error("❌ 缺少 --domain");
    process.exit(1);
  }
  if (!opts.appId) {
    console.error("❌ 缺少 --app-id");
    process.exit(1);
  }
  if (!opts.token) {
    console.error("❌ 缺少 --token");
    process.exit(1);
  }

  return opts as CliOptions;
}

async function main() {
  const opts = parseArgs();

  switch (opts.command) {
    case "get_activity":
      if (!opts.activityId) {
        console.error("❌ 需要 --activity-id");
        process.exit(1);
      }
      await getActivity(opts.domain, opts.appId, opts.token, opts.activityId);
      break;
    case "create_activity":
      if (!opts.body) {
        console.error("❌ 需要 --body");
        process.exit(1);
      }
      await createActivity(opts.domain, opts.appId, opts.token, opts.body);
      break;
    // ... 其余 case
  }
}

这种代码最大的问题不是代码长，而是逻辑分散。参数解析、校验、USAGE、错误处理分布在不同地方，加一个命令得改好几处，特别容易漏。

后来我把这块收成了 createRouter：

import { createRouter, writeResult } from "skill-kits/runtime";

// ✅ 声明式版：参数定义、校验、路由收敛在一起
const router = createRouter({
  name: "redbrick-activity",
  description: "...",
  commonArgs: {
    domain: { type: "string", required: true, desc: "平台域名" },
    appId: { type: "string", required: true, desc: "应用 ID" },
    token: { type: "string", required: true, desc: "SSO token" },
  },
});

router.command({
  name: "get-activity",
  description: "查询活动详情",
  args: {
    activityId: { type: "string", required: true, desc: "活动 ID" },
  },
  async handler({ domain, appId, token, activityId }) {
    writeResult(await getActivity(domain, appId, token, activityId));
  },
});

router.command({
  name: "create-activity",
  description: "创建活动",
  args: {
    body: { type: "json", required: true, desc: "活动字段 JSON" },
  },
  async handler({ domain, appId, token, body }) {
    writeResult(await createActivity(domain, appId, token, body));
  },
});

router.run(process.argv.slice(2));

这一层抽完之后，思路会清爽很多：我不需要再盯着“参数是怎么 parse 的”，只需要关心“这个命令需要什么参数，拿到参数后做什么事”。

三、stdout 和 stderr 混在一起，Agent 根本分不清

之前写 Skill 需要打印信息时，除了错误用 console.error，其他都用 console.log 一把梭。结果 LLM 要从 stdout 里猜哪个是 JSON 结果、哪个是进度日志——猜错了就是一次无效调用。

更好的做法是：stdout 输出 JSON 结果，stderr 输出进度文案；失败时通过非 0 退出码让 Agent 识别到 status: failed，这比让 LLM 去解析 stderr 里的错误文本可靠得多。

skill-kits 提供了几个简单的输出函数，便于使用：

writeResult(payload);                          // stdout：单行 JSON，给 Agent 用
writeError(errorOrMessage, { code?, extra? }); // stderr：结构化错误 + exitCode=1
notify("正在拉取数据...");                      // stderr：进度日志

四、Agent 以为进程卡死了，其实只是在等 60 秒回调

D2C 生码、SSO 登录回调这类场景，最大的问题往往不是"真的超时"，而是"看起来像超时"。

比如你直接睡 60 秒：

await new Promise((resolve) => setTimeout(resolve, 60_000));

进程在这 60 秒内没有任何输出，Agent 很可能会认为进程已经卡死而将其终止。

所以我后来补充了 sleepWithHeartbeat：

import { sleepWithHeartbeat } from "skill-kits/runtime";

await sleepWithHeartbeat(60_000, {
  message: (rem) => `等待生码... 剩余 ${rem}s`,
});

它每 5 秒往 stderr 输出一次心跳，让 Agent 知道进程还在运行，避免因长时间无输出而被误判为卡死。

五、SKILL.md 写得"对"，不等于真的"好用"

这一点我一开始其实没太当回事，后来被现实教育了。

遇到过两个相关的坑：

• 触发不准：description 写得抽象、没有覆盖某些场景，LLM 不知道什么时候该用它，得反复调关键词
• 内容太"全"反而难用：AI 生成的 SKILL.md 内容很全，但我想自己动手改时，感觉无从下手

SKILL.md 这东西当然不可能像代码一样完全标准化，可它也不是完全没法校验。至少这些问题，应该在本地就拦住：

• name 和目录名不一致
• body 太长，把上下文窗口塞爆
• references 引错了路径
• description 太短，看不出触发场景

skill-kits 补了一套围绕 SKILL.md 的 lint 规则，pnpm build 默认先跑：

• name-matches-dir：name 必须等于父目录名
• body-line-limit：body 超过 500 行直接报错
• body-line-soft：超过 400 行给 warning，建议拆到 references/
• description-length：description 太短给 warning
• description-trigger / description-negative：检查有没有写清楚"何时触发"和"不要触发"

如果对阈值有自己的习惯，也可以配 .skillkitrc.json：

{
  "lint": {
    "triggerHints": ["何时", "trigger", "use when"],
    "negativeHints": ["不要", "do not"],
    "descriptionMinChars": 80,
    "bodyLinesWarn": 400,
    "bodyLinesFail": 500
  }
}

另外，runtime 之外还有一层复用也很值得抽：内部 API 客户端、域名常量、签名工具这些跨 Skill 的小工具。skill-kits init 生成的 workspace 默认带一个 packages/shared：

import { signRequest, BIZ_DOMAINS } from "@skills/shared";

构建时 esbuild 会把用到的部分内联进产物，最后还是单文件、零依赖。

六、改一行代码，要 build → cp -r → 再试一次

开发 Skill 时，需要将其同步到 Agent 的本地 Skill 目录以便快速验证。

以前这一步基本都是手动复制：

cp -r dist/xxx ~/.agent/skills

次数多了难免繁琐，因此我添加了 dev 模式：

pnpm dev daily-report --out ~/.agent/skills

它会同时做两件事：

1. 用 esbuild watch src/，.ts 文件变化触发重编
2. 监听 SKILL.md / references/ / assets/，资源变化直接同步到 --out 指定目录

这样我本地改完，Agent 下次调用拿到的就是最新版本。

七、Skill 坏了才知道，因为从来没跑过测试

Skill 是在 Agent 里无人值守跑的，一个命令坏了代价会比普通 CLI 高——因为你常常要等到某次运行失败时才发现。写点单测是值得的。

skill-kits 对测试的设计很简单：测试文件放在 src/**/*.test.ts，通过 pnpm test 执行，底层走 node:test + tsx，零配置。

常见的测试目标其实就一个：断言命令的退出行为——它往 stdout 写的 JSON 是什么样的，它的退出码是 0 还是 1，失败时 stderr 是什么错误。

围绕这个目标，skill-kits/testing 提供了两个 helper：

• captureOutput(fn)：抓 writeResult / writeError / notify 的输出，以及 process.exitCode
• mockFetch(routes)：替换全局 fetch，不打真实网络

一个典型的成功路径测试大概长这样：

import { test } from "node:test";
import assert from "node:assert/strict";
import { mockFetch, captureOutput } from "skill-kits/testing";
import { createActivity } from "./commands/create-activity.js";

const ctx = { domain: "https://example.com", token: "t" };

test("create-activity 返回后端数据且 ok", async () => {
  const mock = mockFetch([
    { match: /\/activity\/create/, json: { code: 0, data: { activity_id: 9001 } } },
  ]);
  try {
    const { json, exitCode } = await captureOutput(() =>
      createActivity(ctx, { act_name: "test" }),
    );
    assert.equal(exitCode, 0);
    assert.equal((json as { activity_id: number }).activity_id, 9001);
  } finally {
    mock.restore();
  }
});

对于纯函数，两个 helper 都不需要，直接 import 后断言即可。对于错误路径，命令内部 throw 一个 SkillError（路由层会把它映射成退出码 1 + stderr JSON），在测试里用 assert.rejects 就能抓到。

顺便提一句：mockFetch 对没匹配上的请求会故意抛错，这样漏写 mock 绝不会悄悄通过，避免"测试通过但线上不通"的尴尬。

日常闭环其实就是三条命令：

pnpm new daily-report
# ... 写代码 + 写测试 ...
pnpm test daily-report     # 跑单测
pnpm build daily-report    # lint → 打包 → zip

写在最后

skill-kits 做的事情很明确：把入口、产物、运行时、定义校验这些横切问题收进一层护栏里，让你在新建第 5 个、第 10 个 Skill 时，脑子里想的依然是业务逻辑怎么写。

如果你也在写 Agent Skill，欢迎试试：

npx skill-kits init my-skills

GitHub 地址：github.com/weijhfly/sk…