企业官网建设流程全解析

1. 从"skills"这个热词说起：它到底指什么

最近一段时间，"skills"这个词在技术社区里出现的频率明显高了起来。如果你只是偶尔刷到，可能会以为它说的是"技能"这个泛泛的概念，但实际在当下的语境里，它已经变成了一个相当具体的技术名词——Agent Skills，也就是给 AI 智能体（Agent）挂载的"技能包"。

我最早接触这个概念是在折腾 Google Cloud 上的一些 Agent 项目时。当时的需求很朴素：我手头有一个能对话的模型，但它只会"说"，不会"做"。我想让它能读文件、能跑命令、能调用外部工具、能按固定流程完成一套操作。传统的做法是写一堆函数调用（function calling）的胶水代码，每个能力都要自己定义 schema、自己处理参数解析、自己兜底异常。写多了就发现，这套东西高度重复，而且换个模型、换个平台就得重写一遍。

Agent Skills 想解决的就是这个问题。它把"一个具体能力"抽象成一个可复用、可分发、可组合的单元。你可以把它理解成给 Agent 用的"插件"或者"App"——一个 skill 通常包含一段说明（告诉模型这个技能是干什么的、什么时候该用）、一份执行逻辑（可能是脚本、可能是提示词模板、可能是对某个工具的封装），以及必要的元数据。Agent 在运行时根据任务需要，动态地"装载"和"调用"这些 skill。

关键词里还出现了npx、GKE、Google Cloud、Agent Skills这几个词，基本能勾勒出典型的使用场景：在云端（Google Cloud / GKE）跑 Agent，通过 npx 这类包管理方式安装和分发 skills。热搜词里还有claude agent skills、codex skills、skills开发、skills安装包下载等等，说明大家关心的核心问题集中在三块：怎么装、怎么用、怎么自己写。

这篇文章我打算把这三块都讲透。不管你是刚听说这个词想搞明白它是什么，还是已经上手但卡在安装或开发环节，或者想搞清楚它和传统 function calling、MCP 这些方案的区别，我都会按我实际踩过的路子来讲。文章偏实战，会有具体的命令、目录结构、代码片段，也会讲清楚每一步"为什么这么做"。

提示：Agent Skills 目前生态还在快速演进，不同平台（Google Cloud、Anthropic 系、OpenAI 系）的实现细节有差异。本文以通用原理和最常见的落地方式为主，具体 API 名称请以你所用平台的当期文档为准。

2. Agent Skills 和传统方案的本质区别

在动手之前，有必要先把概念理清楚。很多人第一次听到 skills，第一反应是"这不就是 function calling 换了个名字吗"。我一开始也这么想，但用下来发现两者的设计哲学差别挺大，理解这个差别能帮你少走很多弯路。

2.1 从"函数"到"技能包"的抽象升级

传统的 function calling，粒度是"函数"。你定义一个get_weather(city)，模型在需要的时候调用它，返回结果。这个模型很直接，但问题是：一个真实任务往往需要多个函数按特定顺序、带特定上下文地组合。比如"帮我分析这个项目的依赖有没有安全漏洞"，背后可能是：读 package.json → 查依赖列表 → 逐个查漏洞库 → 汇总报告。你要么写一个巨大的函数把这些都包进去，要么让模型自己编排，但模型编排容易出错。

Skill 的粒度更接近"一个完整的能力单元"。它不只是暴露一个函数，而是把触发条件、执行步骤、依赖工具、输出格式打包在一起。模型看到的是一个"技能描述"，它知道"当用户要做依赖安全分析时，可以用这个 skill"，至于内部怎么一步步执行，skill 自己封装好了。

打个比方：function calling 像是给你一堆零件（螺丝、齿轮、电机），你得自己组装；skill 像是给你一个组装好的模块（比如一个完整的电钻），你插上电就能用。前者灵活但费劲，后者开箱即用但需要有人提前做好模块。

2.2 Skill 的典型组成结构

一个标准的 skill 目录，通常长这样：

my-skill/ ├── SKILL.md # 技能说明：干什么、何时用、怎么用 ├── skill.json # 元数据：名称、版本、依赖、入口 ├── scripts/ # 执行脚本 │ └── run.py └── resources/ # 模板、配置、静态资源 └── template.txt

其中SKILL.md是最关键的文件。它不是给机器读的配置，而是给模型读的自然语言说明。模型在决定要不要用这个 skill 时，主要就是看这份说明。所以写 skill 的一大半功夫，其实花在"怎么把这份说明写清楚"上。

skill.json则负责机器可读的部分，比如：

{ "name": "dependency-audit", "version": "1.0.0", "description": "分析项目依赖的安全漏洞", "entry": "scripts/run.py", "runtime": "python3", "permissions": ["read:files", "network:outbound"] }

这个结构的好处是关注点分离：模型看 SKILL.md 理解意图，运行时看 skill.json 知道怎么执行，权限系统看 permissions 决定放不放行。

2.3 和 MCP 的关系：不是替代，是互补

热搜词里出现了claude mcpservers npx，说明很多人会把 skills 和 MCP（Model Context Protocol）放一起比较。我的理解是：MCP 解决的是"连接"问题，skills 解决的是"能力封装"问题。

MCP 定义了一套标准协议，让模型能连接到外部的数据源和工具服务器。它管的是"怎么把外部资源接进来"。而 skill 管的是"接进来之后，怎么把一组操作封装成一个可复用的能力"。一个 skill 内部完全可以通过 MCP 去访问外部资源。

所以两者不是二选一。实际项目里常见的组合是：用 MCP 接数据库和 API，用 skills 把这些访问封装成"生成周报""排查线上告警"这样的具体能力。

理解了这张表，你就知道什么时候该用哪个了。简单的一次性工具调用，function calling 足够；要接一堆外部系统，上 MCP；要把常用流程沉淀成可复用资产，写 skill。

3. 安装与运行：npx 那条路到底怎么走

搞清楚概念之后，最实际的问题就是：怎么把 skill 装起来跑起来。热搜里npx playwright install失败、skills安装包下载、claude 国内安装skills 官方市场这些词，说明安装环节是大家卡得最多的地方。我把自己趟过的流程完整讲一遍。

3.1 环境准备：Node 和 npx 是基础

大部分 skill 的分发走的是 npm 生态，所以第一步是把 Node.js 环境弄好。这里有个坑我踩过：Node 版本太低会导致 npx 拉包失败，而且报错信息往往很含糊。

# 检查版本，建议 Node 18 以上 node -v npm -v # 如果版本太低，用 nvm 管理多版本 nvm install 20 nvm use 20

为什么强调 18 以上？因为很多 skill 的运行时代码用了较新的 ES 特性，以及fetch这类全局 API。Node 16 及以下跑起来会各种undefined is not a function，排查起来很费劲。

npx是 npm 自带的包执行器，它的作用是临时下载并执行一个包，不用全局安装。这对 skill 特别合适——你不想为了试一个 skill 就把它永久装到全局，npx 让你"用完即走"。

3.2 安装一个 skill 的标准流程

假设你要装一个社区里的 skill，典型命令是：

# 方式一：直接从 npm 源执行 npx @some-org/some-skill install # 方式二：先下载到本地再装 npx skills-cli add dependency-audit

这里skills-cli是一个常见的 skill 管理工具（不同平台名字可能不同，有的叫skill，有的叫agent-skills）。它的核心命令一般有这么几个：

• add <skill-name>：安装一个 skill
• list：列出已安装的 skill
• remove <skill-name>：卸载
• run <skill-name>：手动触发执行

安装完成后，skill 通常会被放到一个约定目录，比如：

~/.agent/skills/ # 用户级 ./.agent/skills/ # 项目级

项目级和用户级的区别很重要：项目级的 skill 只在这个项目里生效，适合团队协作时把 skill 跟着代码一起提交；用户级的全局生效，适合你个人常用的工具。我一般把通用工具放用户级，把和具体项目强相关的放项目级。

3.3 npx 安装失败的几种典型情况和处理

npx playwright install失败这个热搜词很典型，它反映的是skill 依赖的底层工具在安装时挂掉。我遇到过几类：

第一类：网络超时。npx 要从 registry 拉包，网络不稳时会卡住或超时。处理办法是配置镜像源：

npm config set registry https://registry.npmmirror.com

第二类：权限不足。在 Linux 或容器环境里，npx 想写缓存目录但没权限。报错通常是EACCES。解决办法是改缓存目录到有权限的地方：

npm config set cache /tmp/npm-cache

第三类：底层二进制下载失败。像 playwright 这种，它本身是个 npm 包，但运行时需要下载浏览器二进制。这一步走的是另一套下载逻辑，不走 npm registry，所以配了镜像也没用。常见处理是设置专门的下载源环境变量，或者手动下载后放到指定目录。

第四类：版本冲突。项目里已有依赖和 skill 依赖的版本打架。这时候用npm ls看依赖树，找到冲突点，用overrides字段强制统一版本。

注意：安装失败时，先看完整报错栈，不要只看最后一行。很多失败的真实原因藏在中间几行，比如某个 postinstall 脚本执行失败。

3.4 在 GKE 上跑 skill 的特殊考虑

如果你的 Agent 是部署在 GKE（Google Kubernetes Engine）上的，安装 skill 的逻辑要调整。容器环境是临时的，你不能指望手动装一次就一直在。正确做法是把 skill 安装写进镜像构建流程。

FROM node:20-slim WORKDIR /app COPY package.json ./ RUN npm install # 在构建阶段就把 skill 装好 RUN npx skills-cli add dependency-audit COPY . . CMD ["node", "agent.js"]

这样每次 Pod 启动，skill 都是现成的。如果 skill 需要动态更新，可以挂一个持久卷（PersistentVolume）到 skills 目录，或者用一个 initContainer 在启动前拉取最新版本。

在 GKE 上还有个细节：skill 如果要访问集群内的服务，权限配置要走 ServiceAccount。别在 skill 里硬编码凭证，用 Workload Identity 把 K8s 的 ServiceAccount 和云上的 IAM 绑起来，skill 代码里直接用默认凭证链就行。

4. 自己写一个 skill：从需求到落地

装别人的 skill 只能解决通用问题，真正体现价值的是把你自己的业务流程沉淀成 skill。我写过几个内部用的 skill，这里拿一个真实例子完整走一遍：一个"代码变更影响分析"的 skill。

4.1 先想清楚：这个 skill 的边界在哪

写 skill 最容易犯的错是贪大求全。我第一个 skill 想做成"什么都能干"的万能助手，结果 SKILL.md 写了三千字，模型反而不知道该什么时候用它。

正确的做法是一个 skill 只干一件事，而且这件事的触发条件要清晰。我最后把需求收敛成：给定一个代码仓库和一次提交，分析这次提交可能影响哪些模块、哪些测试需要重跑。

这个边界很清晰：输入是仓库路径 + commit hash，输出是影响范围报告。触发条件是"用户要求分析某次代码变更的影响"。

4.2 SKILL.md 怎么写才能让模型"看懂"

SKILL.md 是 skill 的灵魂。它要回答三个问题：这个技能是干什么的、什么时候该用、用了之后会发生什么。我总结了一个模板：

# 代码变更影响分析 ## 用途 分析指定 commit 的代码变更，输出受影响的模块列表和建议重跑的测试。 ## 何时使用 当用户提出以下类型请求时使用： - "分析这次提交的影响范围" - "这个改动会影响哪些模块" - "帮我看看这次变更要重跑哪些测试" ## 输入 - repo_path: 代码仓库的本地路径（必填） - commit_hash: 要分析的提交哈希（必填） - depth: 分析深度，可选 shallow/deep，默认 shallow ## 输出 一份 Markdown 报告，包含： 1. 变更文件列表 2. 受影响的模块（基于依赖图） 3. 建议重跑的测试用例 ## 限制 - 仅支持 Git 仓库 - deep 模式需要仓库已构建依赖图，否则自动降级为 shallow

这份说明的关键在于触发条件写得具体。不要写"用于代码分析"这种模糊的话，要写清楚用户可能怎么问。模型是靠语义匹配来决定用不用 skill 的，你给的例子越贴近真实提问，命中率越高。

4.3 执行逻辑：脚本还是提示词

skill 的执行逻辑有两种实现方式，选择哪种取决于任务性质。

确定性任务用脚本。比如"读文件、跑 git 命令、解析输出"这种，逻辑固定，用脚本最稳。我的影响分析 skill 主体就是一个 Python 脚本：

import subprocess import sys import json def get_changed_files(repo_path, commit_hash): result = subprocess.run( ["git", "-C", repo_path, "diff-tree", "--no-commit-id", "--name-only", "-r", commit_hash], capture_output=True, text=True ) if result.returncode != 0: raise RuntimeError(f"git 命令失败: {result.stderr}") return [f for f in result.stdout.strip().split("\n") if f] def analyze_impact(repo_path, commit_hash, depth="shallow"): changed = get_changed_files(repo_path, commit_hash) # 基于文件路径推断模块 modules = set() for f in changed: parts = f.split("/") if len(parts) > 1: modules.add(parts[0] + "/" + parts[1]) return { "changed_files": changed, "affected_modules": sorted(modules), "depth": depth } if __name__ == "__main__": repo = sys.argv[1] commit = sys.argv[2] depth = sys.argv[3] if len(sys.argv) > 3 else "shallow" print(json.dumps(analyze_impact(repo, commit, depth), ensure_ascii=False))

需要判断和生成的任务用提示词。比如"根据影响范围写一段给团队看的说明"，这种没有固定答案，交给模型生成更合适。可以在 skill 里放一个提示词模板，脚本跑完拿到结构化结果后，再喂给模型生成自然语言报告。

我的做法是两者结合：脚本负责确定性的数据收集和计算，提示词负责最后的表达和总结。这样既保证了准确性，又保留了灵活性。

4.4 skill.json 里的权限声明别偷懒

很多人写 skill 时忽略permissions字段，觉得反正能跑就行。这是个隐患。权限声明的作用是让运行时知道这个 skill 需要什么能力，从而决定是否放行、是否需要用户确认。

{ "name": "code-impact-analysis", "version": "1.0.0", "description": "分析代码变更的影响范围", "entry": "scripts/analyze.py", "runtime": "python3", "permissions": [ "read:files", "exec:git" ], "inputs": { "repo_path": {"type": "string", "required": true}, "commit_hash": {"type": "string", "required": true}, "depth": {"type": "string", "enum": ["shallow", "deep"], "default": "shallow"} } }

把权限写清楚，一方面安全，另一方面也方便别人审查你的 skill 会不会干坏事。社区里分发 skill 时，权限声明是重要的信任依据。

5. 调试与排错：skill 不生效时怎么查

skill 写完不代表就能用。我遇到过的"skill 明明装了但模型就是不用"的情况，比安装失败还多。这一节讲讲排查思路。

5.1 模型不调用 skill 的三种原因

原因一：SKILL.md 的触发条件写得太窄或太模糊。模型判断要不要用 skill，主要看描述和当前任务的语义匹配度。如果你只写了"分析代码变更"，但用户问的是"这次改动影响大不大"，匹配度就低。解决办法是多写几个触发示例，覆盖不同的表达方式。

原因二：skill 描述和别的 skill 冲突。如果你装了两个功能相近的 skill，模型可能选错或者干脆不用。这时候要检查list输出，看有没有功能重叠的，把不用的卸掉。

原因三：上下文里 skill 信息没被加载。有些平台需要显式开启 skill 加载，或者 skill 目录不在默认搜索路径里。检查一下 skill 是不是放在了运行时能扫到的位置。

排查这类问题，我一般会打开调试日志，看模型在决策时到底看到了哪些 skill 描述、它选择了哪个、理由是什么。大部分平台都有 verbose 或 debug 模式，别嫌日志多，这是最快的定位手段。

5.2 脚本执行报错的定位方法

脚本类 skill 报错，排查相对直接。关键是把 skill 当成普通脚本单独跑一遍，脱离 Agent 环境：

# 直接执行，看原始报错 python3 scripts/analyze.py /path/to/repo abc123 # 检查依赖是否齐全 pip list | grep -i required-package

如果单独跑没问题，但通过 Agent 跑就出错，那问题多半在参数传递或环境差异上。参数传递常见问题是类型不对（比如 Agent 传了字符串 "3" 而脚本期望整数 3），环境差异常见问题是 Agent 运行时的 PATH、工作目录和你的终端不一样。

我踩过一个坑：脚本里用了相对路径读配置文件，终端里跑没问题，因为我在项目根目录；但 Agent 运行时工作目录是别的地方，就找不到文件了。解决办法是脚本里一律用绝对路径，或者基于脚本自身位置计算路径：

import os BASE_DIR = os.path.dirname(os.path.abspath(__file__)) config_path = os.path.join(BASE_DIR, "..", "resources", "config.json")

5.3 超时和资源限制的处理

Agent 环境通常对 skill 执行有时间限制。如果一个 skill 跑太久，会被强制中断。我的影响分析 skill 在大型仓库上就遇到过超时。

处理思路有两个：一是优化脚本本身，比如用git diff-tree而不是遍历所有文件；二是把长任务拆成异步，skill 先返回一个任务 ID，后台慢慢跑，用户过一会儿再来查结果。

# 异步模式示意 def start_analysis(repo, commit): task_id = generate_task_id() # 丢到后台队列 queue.enqueue(analyze_impact, repo, commit, task_id) return {"task_id": task_id, "status": "running"} def check_status(task_id): return queue.get_status(task_id)

对于确实需要长时间运行的 skill，异步是更稳妥的设计。别硬扛超时限制，那只会让用户体验变差。

6. 把 skill 用出花：几个实战场景

概念、安装、开发、调试都讲完了，最后分享几个我实际用 skill 解决问题的场景，给你一些组合思路。

6.1 用 skill 固化团队的代码审查流程

我们团队有一套代码审查清单，但新人经常漏项。我把它做成了一个 skill：输入 PR 号，自动拉取变更、按清单逐项检查（有没有加测试、有没有改文档、有没有引入新依赖）、生成审查报告。

这个 skill 的价值不在于技术多复杂，而在于把隐性知识显性化。以前审查标准在老人脑子里，现在写进 skill，新人也能按标准走。

6.2 把重复的运维操作封装成 skill

线上排查经常要做一套固定动作：看日志、查指标、比对配置。我把这套流程做成 skill，输入服务名和时间范围，自动跑完这些检查，输出一份排查摘要。

这里有个经验：skill 的输出格式要固定。我一开始让模型自由发挥，结果每次报告结构都不一样，后来强制用模板，可读性好了很多，也方便后续做自动化处理。

6.3 skill 的组合使用

单个 skill 能力有限，但组合起来就很强。比如"发布前检查"这个场景，可以串起三个 skill：代码影响分析 → 测试覆盖检查 → 变更日志生成。Agent 根据任务自动编排这几个 skill 的执行顺序。

组合的关键是skill 之间的输入输出要能对接。前一个 skill 的输出格式，最好就是后一个 skill 能直接吃的输入格式。设计 skill 时多想想"它会不会和别的 skill 配合"，接口设计会更合理。

6.4 关于 skill 分发和版本管理

如果你想把 skill 分享给团队或社区，版本管理要认真做。我的做法是每个 skill 独立仓库，用语义化版本，重大改动升主版本号。skill.json 里的 version 字段要和 git tag 对上。

分发渠道上，内部用私有 npm registry，公开的走公共 registry。安装时指定版本号，避免自动升级带来的意外：

npx skills-cli add code-impact-analysis@1.2.0

别用latest，生产环境里版本锁定是基本纪律。我见过因为 skill 自动升级导致行为变化、线上流程出问题的案例，教训很实在。

写 skill 这件事，说到底是在把你的经验变成可复用的资产。一开始可能觉得麻烦，但当你发现自己上周写的 skill 这周又救了自己一次，就会明白这个投入是值得的。我现在的习惯是，任何重复做了三次以上的操作，就考虑把它沉淀成 skill。这个习惯坚持下来，手头的工具库越来越厚，干活也越来越省心。