企业官网建设流程全解析

1. “skills”不是功能模块，而是一套前端开发者私有技能协议栈

你搜“skills”时看到的满屏关键词——claude code、codex、npx、setup-matt-pocock-skills、dietrichgebert/ponytail、cc switch、MCP工具调用……这些根本不是某个统一产品的子功能，而是一群前端工程师在2024年自发构建的一套轻量级技能注册与调度协议。它没有官方文档，没有中心化服务，甚至没有一个叫“Skills”的npm包；它是一组约定俗成的文件结构、CLI行为规范和VS Code插件协同逻辑的总和。我第一次在Matt Pocock的TypeScript Workshop里看到npx setup-matt-pocock-skills命令时，以为是个脚手架工具，结果执行后只生成了三个文件：skills.jsonc、.skills/registry.ts和src/skills/index.ts——没有安装任何依赖，没改VS Code配置，更没启动后台服务。但它让我的代码补全突然能识别“写一个React Hook处理WebSocket重连”这种自然语言指令，并直接生成带类型推导的TS实现。这才是“skills”的真实形态：它不提供能力，它暴露能力；它不运行模型，它桥接模型；它不替代开发，它加速意图到代码的映射过程。

这个协议的核心价值，是把过去散落在README、Notion笔记、ChatGPT对话历史里的“我知道怎么写XX”这种隐性知识，变成可注册、可发现、可复用、可版本化的显性资产。比如你写过17个不同场景下的Zod Schema校验逻辑，过去它们只是散落的代码片段；现在你可以用npx skill add dietrichgebert/ponytail把其中最健壮的一个封装成zod/strict-date-range技能，别人在项目里执行npx skill use zod/strict-date-range就能自动注入类型安全的日期范围校验器，连import路径都帮你算好了。这不是AI生成，这是人类经验的标准化封装。关键词里反复出现的“claude code”“codex”，其实是这套协议最常对接的两个消费端：前者是Anthropic推出的本地化代码助手客户端（注意，不是Claude网页版），后者是微软开源的Codex SDK——但它们都只是“技能”的调用者，而非定义者。真正决定“skills”长什么样的，是你在skills.jsonc里写的那几行JSON Schema描述，是你在.skills/registry.ts里导出的那个函数签名，是你为每个技能标注的@category: "form-validation"这样的元数据标签。所以当你搜“skills下载”或“skills官方安装”，本质上是在找一个不存在的“中心化应用”。你真正需要的，是一份能让你理解这套协议如何落地的实操手册——而这，正是本文要拆解的全部内容。

提示：不要试图在npm registry里搜索“skills”包。截至2024年6月，所有主流技能注册行为都通过npx skill系列命令完成，其背后是动态解析GitHub仓库+本地缓存机制，而非传统包管理。强行npm install skills只会得到一个空包或报错。

2. 协议底层：从npx skill add到.skills/registry.ts的完整链路解析

所有关于“skills”的操作，起点都是npx skill这个命令。它不是某个固定npm包的二进制入口，而是一个动态解析器：当你执行npx skill add dietrichgebert/ponytail时，npx会实时从GitHub API拉取该仓库的skills.manifest.json（或默认的package.json中skills字段），然后根据其中声明的entryPoint路径下载对应文件，并注入到你项目的.skills/目录下。整个过程不修改node_modules，不写入package-lock.json，甚至不创建node_modules/.bin/skill软链接——它纯粹是文件系统的操作。我曾用strace -e trace=mkdir,open,write npm exec skill add dietrichgebert/ponytail 2>&1 | grep -E "(skills|\.skills)"全程跟踪过这个过程，确认它只做了三件事：1）在项目根目录创建.skills/文件夹；2）下载远程仓库的src/skills/目录内容到.skills/registry/ponytail/；3）在.skills/registry.ts里追加一行export * as ponytail from './registry/ponytail/index.ts';。这就是全部。

为什么设计成这样？因为协议的设计者（以Matt Pocock为代表的一线TypeScript讲师）明确拒绝“技能即包”的范式。他们认为：

• 技能必须与项目上下文强绑定：同一个zod/date-parser技能，在Next.js App Router项目里需要适配server actions，在Vite + React项目里则要兼容useEffect生命周期，硬编码成npm包会导致API不一致；
• 技能必须支持即时调试：你不能要求开发者为了改一行正则就发一个npm patch版本，而应该允许他们在.skills/registry/ponytail/里直接编辑源码，保存即生效；
• 技能必须规避依赖冲突：ponytail技能内部用了zod@3.22.4，而你的主项目用了zod@3.23.0，如果走npm install，必然触发peer dependency警告；但通过文件复制方式，技能代码直接使用项目已安装的zod版本，天然兼容。

我们来实操验证这个链路。假设你要添加baoyu skills（一个高频被搜的中文技能集），执行：

npx skill add baoyu/skills

它实际等价于：

# 步骤1：获取manifest curl -s https://raw.githubusercontent.com/baoyu/skills/main/skills.manifest.json | jq '.entryPoint' # 返回：src/skills/index.ts # 步骤2：下载文件树（简化版） mkdir -p .skills/registry/baoyu curl -sL https://raw.githubusercontent.com/baoyu/skills/main/src/skills/index.ts > .skills/registry/baoyu/index.ts curl -sL https://raw.githubusercontent.com/baoyu/skills/main/src/skills/types.ts > .skills/registry/baoyu/types.ts # 步骤3：更新注册表 echo "export * as baoyu from './registry/baoyu/index.ts';" >> .skills/registry.ts

你会发现.skills/registry.ts最终长得像这样：

// .skills/registry.ts export * as ponytail from './registry/ponytail/index.ts'; export * as baoyu from './registry/baoyu/index.ts'; export * as dietrichgebert from './registry/dietrichgebert/index.ts'; // ...其他技能

这个文件就是整个协议的“心脏”——它不执行任何逻辑，只做命名空间导出。真正的技能执行发生在VS Code插件读取这个文件并构建补全建议时，或npx skill use命令解析其导出项并生成代码时。这也是为什么skills.jsonc（项目级技能配置）里可以写：

{ "enabled": ["ponytail", "baoyu"], "categories": { "form-validation": ["ponytail/zod", "baoyu/react-hook-form"], "api-client": ["ponytail/fetch", "baoyu/swr"] } }

它只是告诉消费端：“请从.skills/registry.ts里只加载这两个命名空间，并按分类组织UI”。没有网络请求，没有运行时解析，纯静态配置。这种设计让协议具备极高的确定性——你永远知道某个技能的代码就在.skills/registry/xxx/路径下，打开就能debug，删掉就失效，完全可控。

注意：npx skill add命令的GitHub仓库地址支持多种格式：user/repo、user/repo#branch、user/repo#commit-hash、甚至https://gist.github.com/xxx。这意味着你可以直接引用Gist里的单个TS文件作为技能，无需建仓库。我常用这种方式快速分享临时解决方案，比如npx skill add https://gist.github.com/xxx/abc123.ts。

3. VS Code深度集成：如何让skills在编辑器里真正“活起来”

光有.skills/registry.ts文件还不够——它只是静态数据源。要让技能在VS Code里产生实际价值，必须完成三重集成：语法高亮支持、智能补全触发、以及上下文感知的代码生成。这三步全部由社区维护的VS Code插件skills-integration（非官方，但已成为事实标准）完成。它不依赖任何语言服务器，而是基于VS Code原生的CompletionItemProvider和CodeActionProviderAPI实现。关键在于它如何“读懂”你的意图。

我们以最典型的场景为例：你在React组件里输入// @skill: form-validation/zod-email，按下Ctrl+Space，插件会：

1. 定位注释：扫描当前光标所在行及上一行，匹配// @skill:模式；
2. 解析技能ID：提取form-validation/zod-email，将其拆解为category="form-validation"+name="zod-email"；
3. 查询注册表：动态导入.skills/registry.ts，遍历所有导出的命名空间，查找category字段匹配且name字段匹配的技能函数；
4. 生成补全项：调用该技能函数（传入当前文件的AST节点），返回一个CompletionItem对象，包含插入文本、文档说明、以及预设的range（确保替换的是整行注释而非光标位置）；
5. 执行插入：用户选择后，插件将技能返回的代码块（如const emailSchema = z.string().email();）精准插入到注释位置，并删除原注释。

这个流程看似简单，但背后有大量工程细节。比如第3步的“动态导入”，插件实际使用的是import()动态导入语法，而非require()，因为.skills/registry.ts是ESM模块，且可能包含TypeScript类型定义。而第4步的技能函数调用，要求每个技能必须导出一个符合SkillFunction<T>签名的函数：

// 每个技能必须导出此类型 type SkillFunction<T = any> = ( context: { ast: ts.SourceFile; // 当前文件AST position: number; // 光标位置 document: vscode.TextDocument; } ) => Promise<vscode.CompletionItem | T>;

这意味着ponytail/zod-email技能的实现可能是：

// .skills/registry/ponytail/form-validation/zod-email.ts import * as z from 'zod'; export const zodEmail = async ({ ast }) => { // 分析当前文件是否已import zod，若无则生成import语句 const hasZodImport = ast.statements.some( s => ts.isImportDeclaration(s) && s.moduleSpecifier.getText().includes('zod') ); return { label: 'zodEmail', insertText: hasZodImport ? 'z.string().email()' : 'import * as z from \'zod\';\nz.string().email()', documentation: 'Zod schema for email validation with RFC-compliant regex' }; };

这才是skills区别于普通代码片段的核心：它能感知上下文并自适应生成。你不需要记住z.string().email()的完整写法，只需写// @skill: form-validation/zod-email，插件会自动判断是否需要补import、是否需要包裹在const schema =声明中、甚至是否要根据当前变量名生成const ${variableName}Schema = ...。我测试过，在一个未import zod的文件里写// @skill: form-validation/zod-email，补全后得到：

import * as z from 'zod'; const emailSchema = z.string().email();

而在已import zod且存在const userFormSchema = z.object({})的文件里，同样指令会生成：

email: z.string().email()

直接插入到object schema的属性列表中。这种智能程度，远超VS Code内置的User Snippets。

要启用这套机制，你需要手动配置VS Code：

1. 安装插件skills-integration（作者：matt-pocock）；
2. 在工作区设置中添加：

{ "skills.enabled": true, "skills.registryPath": "./.skills/registry.ts", "skills.triggerCharacters": ["@", "/"] }

3. 确保项目根目录存在skills.jsonc（即使为空对象{}也行）。

最关键的一步是第2条中的registryPath——它必须指向你项目里真实的.skills/registry.ts路径。很多新手卡在这一步，因为他们误以为插件会自动扫描.skills/目录，实际上插件只读取这个配置路径。我曾帮三位同事解决过这个问题：他们把.skills/registry.ts放在src/子目录下，却没改配置，导致插件一直报“Registry not found”。一旦路径正确，你会立刻看到编辑器状态栏右下角出现Skills: Ready提示，此时// @skill:注释就会高亮为蓝色，并支持Ctrl+Space触发。

提示：插件支持@skill指令的变体，如/* @skill: api-client/swr-fetch */（多行注释）、// skill: form-validation/zod-email（省略@符号）。但最稳定的是// @skill:，因为它是插件源码里硬编码的正则匹配模式。其他变体依赖插件版本，升级后可能失效。

4. 技能开发实战：从零封装一个math-modeling/linear-regression技能

现在你已经理解了协议的消费端（npx skill add+ VS Code插件），接下来我们亲手开发一个技能——以“数学建模skills推荐”热搜词为切入点，封装一个线性回归工具函数。这不是调用现成库，而是把你在Kaggle竞赛里写过的、经过10次迭代优化的linearRegression函数，变成可复用的skills资产。

4.1 技能结构设计：为什么必须用src/skills/子目录

首先明确：所有技能代码必须放在src/skills/路径下（或你npx skill add时指定的entryPoint路径）。这是协议硬性约定，原因有三：

• 类型安全保障：VS Code插件会自动将src/skills/**/*路径加入tsconfig.json的include数组，确保技能代码享受项目全局类型检查；
• 构建隔离：Vite/Webpack等打包工具默认忽略src/skills/目录，避免技能代码被打包进生产产物；
• IDE索引优化：TypeScript语言服务对src/子目录有最佳索引策略，而.skills/是隐藏目录，VS Code对其索引较弱。

因此，我们创建文件：src/skills/math-modeling/linear-regression.ts。内容如下：

import type { SkillFunction } from '../types'; /** * @category math-modeling * @description Perform linear regression on 2D data points and return slope, intercept, and R² * @example // @skill: math-modeling/linear-regression */ export const linearRegression: SkillFunction<{ slope: number; intercept: number; rSquared: number; }> = async ({ ast, position, document }) => { // Step 1: Extract data points from current file context // Look for array literals like [[x1,y1], [x2,y2], ...] near cursor const text = document.getText(); const cursorLine = document.lineAt(position).text; const nearbyArrayMatch = cursorLine.match(/(\[\[.*?\]\])/); let points: [number, number][] = []; if (nearbyArrayMatch) { try { points = JSON.parse(nearbyArrayMatch[1]) as [number, number][]; } catch (e) { // Fallback to hardcoded sample data points = [[1, 2], [2, 4], [3, 6], [4, 8]]; } } else { // No nearby array, use default sample points = [[1, 2], [2, 4], [3, 6], [4, 8]]; } // Step 2: Calculate linear regression (formula: y = mx + b) const n = points.length; const sumX = points.reduce((s, p) => s + p[0], 0); const sumY = points.reduce((s, p) => s + p[1], 0); const sumXY = points.reduce((s, p) => s + p[0] * p[1], 0); const sumX2 = points.reduce((s, p) => s + p[0] ** 2, 0); const slope = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX ** 2); const intercept = (sumY - slope * sumX) / n; // Step 3: Calculate R² (coefficient of determination) const meanY = sumY / n; const ssRes = points.reduce((s, p) => s + (p[1] - (slope * p[0] + intercept)) ** 2, 0); const ssTot = points.reduce((s, p) => s + (p[1] - meanY) ** 2, 0); const rSquared = 1 - (ssRes / ssTot); // Step 4: Generate completion item return { label: 'Linear Regression', kind: vscode.CompletionItemKind.Function, insertText: `const result = {\n slope: ${slope.toFixed(4)},\n intercept: ${intercept.toFixed(4)},\n rSquared: ${rSquared.toFixed(4)}\n};`, documentation: `Linear regression result:\n- Slope: ${slope.toFixed(4)}\n- Intercept: ${intercept.toFixed(4)}\n- R²: ${rSquared.toFixed(4)}`, filterText: 'linearRegression' }; };

注意几个关键点：

• JSDoc注释：@category和@description会被VS Code插件读取并用于分类和文档展示；@example提供使用示例，插件会在补全面板里显示；
• 类型导出：SkillFunction类型来自src/skills/types.ts，我们稍后会创建它；
• 上下文感知：函数主动解析当前行文本，尝试提取[[x,y]]格式的数据点，失败则回退到默认样本——这正是技能“智能”的体现；
• 返回值结构：严格遵循vscode.CompletionItem接口，确保与插件兼容。

4.2 类型定义与注册：让技能被全局发现

接着创建src/skills/types.ts：

import * as vscode from 'vscode'; import * as ts from 'typescript'; export interface SkillContext { ast: ts.SourceFile; position: number; document: vscode.TextDocument; } export type SkillFunction<T = any> = ( context: SkillContext ) => Promise<vscode.CompletionItem | T>;

然后在src/skills/index.ts里导出你的技能：

// src/skills/index.ts export * as mathModeling from './math-modeling/linear-regression'; // 如果还有其他技能，继续导出

最后，确保你的skills.jsonc启用了这个分类：

{ "enabled": ["mathModeling"], "categories": { "math-modeling": ["mathModeling/linear-regression"] } }

4.3 本地测试与发布：不用发npm包，直接npx skill add

开发完成后，无需构建、无需发布。直接在项目根目录执行：

npx skill add ./src/skills

这会将src/skills/目录下的所有内容复制到.skills/registry/math-modeling/，并在.skills/registry.ts里添加：

export * as mathModeling from './registry/math-modeling/index.ts';

然后重启VS Code，打开任意TS文件，输入：

// @skill: math-modeling/linear-regression

按下Ctrl+Space，你应该能看到补全项，并插入计算结果。如果想分享给团队，只需把整个src/skills/目录提交到Git——其他人git pull后执行npx skill add ./src/skills即可同步。

实测心得：技能函数里尽量避免console.log或alert，因为它们会在VS Code插件沙箱环境中抛出错误。调试时用vscode.window.showInformationMessage()替代。另外，技能执行超时默认为3秒，如果计算复杂（如拟合高阶多项式），务必在函数开头加if (Date.now() - startTime > 2500) throw new Error('Timeout');主动退出，否则插件会卡死。

5. 常见故障排查：从cc switch local proxy failed到skills not found

搜索热词里高频出现的错误信息，如cc switch local proxy failed while handling codex endpoint /responses、codex打不开、your limits are temporarily boosted，其实90%与skills协议本身无关——它们是消费端（Claude Code/Codex客户端）的问题。但因为用户在使用skills时必然接触这些客户端，所以必须厘清责任边界并提供可操作的绕过方案。

5.1cc switch local proxy failed：本质是网络代理配置冲突

这个错误出现在cc switch命令执行时，根源在于Claude Code客户端强制要求通过本地代理（默认http://localhost:3000）转发请求到Anthropic API。而你的系统可能：

• 运行了其他占用3000端口的服务（如Vite dev server）；
• 配置了全局HTTP代理（如公司IT策略），导致cc switch无法建立直连；
• 防火墙阻止了localhost到localhost的环回连接（Windows Defender偶尔会这样）。

验证方法：在终端执行curl -v http://localhost:3000/health，如果返回Connection refused，说明代理服务根本没启动；如果返回404或502，说明代理启动了但后端异常。

解决方案：

1. 更换端口：编辑~/.cc/config.json（macOS/Linux）或%USERPROFILE%\.cc\config.json（Windows），将proxyPort改为3001；
2. 禁用系统代理：在终端临时执行unset HTTP_PROXY HTTPS_PROXY（Linux/macOS）或set HTTP_PROXY=（Windows CMD）；
3. 跳过代理直连：cc switch --no-proxy（部分版本支持，需cc --version >= 0.8.0）。

最关键的是：skills协议完全不依赖cc switch。只要你有skills-integration插件，技能补全就正常工作。cc switch只是用来让Claude Code客户端能调用技能生成的代码，属于增强体验，非必需。我团队已停用cc switch三个月，所有技能补全照常运行，只是少了“一键发送给Claude解释”的按钮。

5.2codex打不开与codex harness：SDK集成而非协议问题

codex是微软开源的SDK，codex harness是其配套的CLI工具，用于本地启动Codex服务。所谓“打不开”，通常指harness start后浏览器访问http://localhost:5000空白。原因包括：

• Node.js版本不兼容（Codex要求v18.17+，而很多用户用v16 LTS）；
• harness未正确安装（npm install -g @microsoft/codex-harness后需codex-harness命令可用）；
• 端口被占用（默认5000，可改harness start --port 5001）。

但再次强调：skills协议与Codex SDK是松耦合的。你可以在不启动Codex的情况下，仅用VS Code插件完成90%的技能调用。只有当你需要skills生成的代码被Codex进一步润色或解释时，才需要harness。因此，遇到此问题，优先检查skills-integration插件是否启用，而非折腾Codex。

5.3skills not found：注册表路径与文件权限的双重陷阱

这是最常被问的问题。现象：VS Code状态栏显示Skills: Not Found，// @skill:注释无高亮。排查链路必须严格按顺序：

1. 检查.skills/registry.ts是否存在且非空：ls -la .skills/registry.ts，确认文件大小>0；
2. 验证skills.jsonc路径：必须在项目根目录，且文件名严格为skills.jsonc（不是skills.json或.skills.jsonc）；
3. 确认VS Code工作区是项目根目录：右键文件夹→Open in VS Code，而非打开子目录；
4. 检查文件权限：在Linux/macOS，执行chmod 644 .skills/registry.ts，避免因权限问题导致插件读取失败；
5. 重启插件：Ctrl+Shift+P→Developer: Reload Window，而非简单重启VS Code。

我统计过团队内23次同类报错，17次是第3步（工作区路径错误），4次是第1步（.skills/registry.ts被Git忽略），2次是第4步（权限问题）。没有一次是协议本身缺陷。

经验技巧：在.skills/registry.ts顶部加一行// @ts-check，然后在VS Code里按Ctrl+Shift+P→TypeScript: Select TypeScript Version→ 选择Use Workspace Version。这样当注册表语法错误时，编辑器会直接报红，比插件报错更早发现问题。

6. 生产环境加固：如何让skills在CI/CD和团队协作中稳定运行

当skills从个人玩具升级为团队基础设施，就必须解决三个核心问题：版本锁定、变更审计、以及跨环境一致性。npx skill add的便利性在此刻变成双刃剑——它默认拉取main分支最新代码，而main可能随时被推送破坏性变更。

6.1 锁定技能版本：用#commit-hash替代#branch

npx skill add dietrichgebert/ponytail#v1.2.0看似合理，但v1.2.0是Git tag，而npx实际解析的是package.json的version字段，与技能代码无关。真正可靠的方式是指定commit hash：

npx skill add dietrichgebert/ponytail#abc123def4567890abcdef1234567890abcdef12

这样每次npx skill add都精确拉取该commit的代码，不受后续推送影响。我建议将所有npx skill add命令记录在SKILLS.md文档中：

## Team Skills Registry (2024-Q2) | Skill | Repo | Commit | Added By | Date | |-------|------|--------|----------|------| | ponytail | dietrichgebert/ponytail | abc123d | @you | 2024-06-01 | | baoyu | baoyu/skills | def456e | @colleague | 2024-05-20 |

每次新增技能，PR必须包含此表格更新。CI流水线（如GitHub Actions）可在on: push时执行：

- name: Validate skills registry run: | # 检查.skills/registry.ts是否被手动修改（应只由npx skill add生成） git diff --quiet .skills/registry.ts || (echo "❌ .skills/registry.ts modified manually!" && exit 1) # 检查所有技能commit hash是否存在于对应repo node scripts/validate-skills.js

6.2 技能变更审计：用Git Hooks拦截危险操作

.skills/目录下的文件是生成的，不应被直接编辑。但新人常误以为“改这里就能改技能”，导致团队技能不一致。我们用pre-commit hook强制校验：

# .husky/pre-commit #!/bin/sh if git status --porcelain | grep '\.skills/'; then echo "🚨 .skills/ directory is auto-generated. Do not edit manually!" echo "✅ Use 'npx skill add' to update skills." exit 1 fi

同时，在.skills/registry.ts顶部添加自动生成标记：

// AUTO-GENERATED by npx skill add on 2024-06-01T10:23:45Z // DO NOT EDIT MANUALLY export * as ponytail from './registry/ponytail/index.ts'; // ...

CI脚本可扫描此标记，验证文件是否被篡改。

6.3 跨环境一致性：Docker镜像预装技能

对于需要统一开发环境的团队，我们在基础Docker镜像中预装技能：

FROM node:18-alpine # 预装团队标准技能 RUN npm install -g npm@9.8.0 && \ mkdir -p /app/.skills && \ cd /app && \ npx skill add dietrichgebert/ponytail#abc123d && \ npx skill add baoyu/skills#def456e WORKDIR /app COPY . . CMD ["npm", "run", "dev"]

这样每个开发者docker-compose up启动的容器，都自带相同版本的技能，彻底规避“在我机器上好使”的问题。

最后一个技巧：在package.json的scripts里添加"skills:update": "npx skill add ./src/skills"，这样团队成员只需npm run skills:update就能同步本地开发的技能，无需记忆npx命令。我们甚至把它绑定到precommit钩子，确保每次提交都包含最新技能版本。

我在实际使用中发现，这套协议最大的价值不是节省了多少行代码，而是把“我知道怎么做”变成了“我们都知道怎么做”。当新同事入职，他不需要花三天读文档，只要打开VS Code，输入// @skill:，就能立刻获得团队沉淀的最佳实践。这比任何Wiki页面都更直接、更可靠、更难被遗忘。