手头攒了 120 多个 Agent Skill 之后我彻底放弃了“手动管理”这条路。早期只有十几个 Skill 时复制粘贴、改改路径还算能撑住后来仓库越拉越多、大家各改各的版本光是核对“当前这个 Skill 到底是哪个仓库来的、版本对不对”就能耗掉半天。我最后造了一套极简的方案把仓库当作源把链接当作安装指令一条命令完成 Skill 的安装、更新和卸载底层思路跟 npm、pip 几乎一模一样只不过这次“安装”的对象是 AI Agent 的技能包。这篇就把这套“Agent Skill 包管理器”的设计思路、实现细节和踩坑实录完整拆开讲一遍。先说清楚这套东西适合谁看。如果你在折腾 Claude Code、Cursor 这类支持 Skill/Agent 机制的 AI 编程工具或者正在给自己团队的 Agent 沉淀一套可复用的技能库又恰好被“Skill 数量一多就乱成一团”这件事困扰那这篇文章很适合你。如果你还在十几二十个 Skill 的规模看完至少能提前避开后面几个大坑。1. 为什么 Agent Skill 也需要一套“包管理器”1.1 先分清三个容易混的概念Agent、Skill、MCP很多刚接触这块的人会把 Agent、Skill、MCP 搅在一起实际它们是三个不同层级的东西。MCPModel Context Protocol解决的是 Agent 如何标准化地调用外部工具和数据源它是偏底层的“接口协议”。你写一个 MCP server本质上是在给 AI 提供一套可被统一发现、统一调用的工具入口。Skill 解决的是 Agent 遇到某类任务时如何组织自己的思考流程、调用哪些工具、按什么顺序执行它更偏“经验沉淀”。Agent 则是一个能自主规划、拆解任务并持续执行的角色单位。我常打的比方是MCP 像墙上的标准插座负责供电协议统一Skill 像你脑子里的“遇到这种情况就走这套流程”的肌肉记忆Agent 是把所有这些组装起来的那个“人”。所以 Skill 是比 Agent 更小的复用粒度一个 Agent 可以挂载十几个 Skill一个 Skill 也可以被不同 Agent 复用。1.2 Skill 数量过百之后手工管理会崩在哪里我最初管理 Skill 的方式极其原始建一个公共目录每个 Skill 一个文件夹改动就直接改文件。这个模式在 20 个以内还能凑合一旦超过 50 个四个问题会接踵而至。第一个是“版本漂移”。同一个 Skill 在不同机器、不同项目里的版本不一致A 同事改了一个文件B 同事完全不知道最后大家调同一个 Agent 行为却不一样。第二个是“来源失忆”。三个月前从某个仓库拉来的 Skill再想找原始出处时已经记不清了后续维护只能靠猜。第三个是“依赖地狱”。一部分 Skill 会依赖另外的公共 Skill 或模板手工管理时完全没有任何依赖声明装漏了只能运行时报错才发现。第四个是“上手成本”。新同学加入项目想配齐环境得靠口头交接、文档手把手拷贝效率低到离谱。这些痛点传统软件开发领域早就经历过并且已经有成熟解法那就是包管理器。1.3 软件包管理器的思路迁移想想我们日常是怎么用包管理器的。Python 用 pip 或 uv 从 PyPI 拉包前端用 npm 从 registry 拉依赖Maven 项目要配中央仓库或镜像仓库Docker 镜像也有 registry 的概念。这些工具的共同点是有一个明确的“源”包有规范的元数据安装动作可以通过一条命令完成并且支持版本管理。那 Agent Skill 为什么不能照搬这套完全能搬。我把 Skill 看成一种特殊的“软件包”把 Git 仓库当成“源”把一条可解析的资源链接当成“安装指令”于是就有了这套非常轻量的包管理器。核心就三句话仓库是源链接是安装清单文件管版本。这套设计最大的价值不是炫技而是让 Skill 管理从一个“靠自觉的文件夹整理问题”变成一个“有标准可依的工程问题”。接下来我详细展开架构上的几个关键选择。2. 这套方案的整体架构“仓库是源链接是安装”2.1 核心抽象把 Skill 当成“可安装的软件包”在设计之前我先定义清楚 Skill 包的最小单元长什么样。一个 Skill 包就是一个包含标准元数据的目录里面必须有SKILL.md文件用来描述这个 Skill 的名称、版本、功能、依赖和入口说明。类比的话SKILL.md就是软件包的package.json或pyproject.toml是整个包管理逻辑的锚点。目录里可以再带辅助资源比如脚本、模板、参考文档它们都算这个 Skill 包的“内容文件”。安装一个 Skill本质上就是把一个远程目录完整地复制到本地某个约定好的 Skills 目录里并在一个全局注册表文件里登记这条记录。为什么必须搞一个注册表文件因为只复制目录是不够的你还需要回答“当前装了哪些包、各自什么版本、来自哪个仓库、升级到哪个版本了”。这些数据用一个 JSON 或 YAML 清单来持久化是整套系统能够追踪状态的基础。2.2 源层设计仓库目录规范与索引文件源选什么我实测下来用 Git 仓库做源是成本最低、最通用的方案。你可以用 GitHub、GitLab、Gitee也可以用自建的 Gitea/Gogs 内部仓库。关键是仓库内部的目录结构要有规范我的推荐结构如下skills-repo/ ├── index.yaml ├── README.md └── skills/ ├── web-extractor/ │ ├── SKILL.md │ ├── scripts/ │ │ └── extract.py │ └── assets/ │ └── prompt-template.md ├── code-reviewer/ │ ├── SKILL.md │ └── templates/ │ └── review-check.md └── html-cleaner/ ├── SKILL.md └── ...index.yaml是源仓库的索引文件相当于软件源的“仓库元数据”。它记录这个源里有哪些包、每个包的最新版本和路径这样客户端可以只拉索引、不拉全仓就能搜索和比对版本。source: https://github.com/example/skills-repo updated: 2025-06-01 packages: - name: web-extractor version: 1.2.0 path: skills/web-extractor description: 从任意网址提取正文并整理为结构化 Markdown - name: code-reviewer version: 0.9.1 path: skills/code-reviewer description: 基于提交记录生成代码评审意见索引文件不强制复杂化能支持“列出所有包”和“定位指定包路径”这两个操作就够用。具体包内的SKILL.md负责描述自身详情索引文件只做轻量登记避免双份维护带来的信息不同步。2.3 安装层设计链接解析、拉取与落盘注册这一层是整套系统的发动机核心任务是把一条链接变成一次安装。我的“链接”约定有几种形式按优先级排列https://github.com/user/skills-repo//skills/web-extractor这种带//的写法表示仓库内的子目录路径这是最常用的形式。https://github.com/user/skills-repo/archive/refs/tags/v1.2.0.tar.gz这种指向压缩包的链接适合脱离 Git 元数据直接安装某次 release。https://gitee.com/user/skills-repo/raw/main/skills/xxx这种 Raw 文件链接适合安装单文件形态的轻量 Skill。安装流程拆成五步解析链接、拉取内容、校验完整性、落盘、注册。每一步都有坑我在第 4 节专门讲。这里先给一个简化版的 Python 实现思路完整代码后面会展示。3. 动手实现写一个简版 Skill 包管理器3.1 环境准备为什么我用 Python uv 搭这个工具我最后实现的时候选了 Python配 uv 做环境和依赖管理。选 Python 的原因很简单跨平台、写 CLI 顺手、团队里懂的人多。选 uv 而不是直接用 pip是因为 uv 创建虚拟环境和安装依赖的速度确实快一条uv sync就把环境全部搞定适合这种需要快速分发的小工具。初始化项目的命令如下uv init askpm cd askpm uv add typer requests uv add --dev pytesttyper用来写命令行参数解析比手写argparse舒服很多自动生成--help还能直接基于函数签名做参数校验。命名上我起名askpm也就是 Agent Skill Package Manager 的缩写方便后面称呼。3.2 SKILL.md 元数据规范与索引生成一个标准的SKILL.md长这样开头用 YAML frontmatter 写元数据--- name: web-extractor version: 1.2.0 description: 从任意网址提取正文并整理为结构化 Markdown author: exampleexample.com license: MIT entry: SKILL.md dependencies: - html-cleaner^1.0.0 tags: [web, extraction] --- # Web Extractor 当用户需要提取网页正文时按以下步骤执行 1. 打开目标网址。 2. 用内置脚本提取正文。 3. 去掉导航、广告等噪声内容。 4. 输出结构化 Markdown。注意dependencies字段它声明这个 Skill 运行需要哪些其他 Skill。这个字段在手工管理阶段纯靠人肉记忆有了它包管理器就能在安装时自动先装依赖项。entry指定 Agent 应该读取哪个文件作为 Skill 的完整定义大多数情况下就是SKILL.md本身。索引文件不需要手写可以用脚本扫描仓库自动生成。核心逻辑就是遍历skills/目录读取每个子目录下SKILL.md的 frontmatter然后汇总成index.yaml。这样源仓库维护者只需要维护每个包的元数据索引永远和实际目录一致。3.3 install 命令的实现链接到安装的完整流转install是整套工具的核心命令我直接给出一个可运行的简化实现方便你理解全链路逻辑# askpm/install.py from pathlib import Path import hashlib import json import tempfile import subprocess import shutil import typer SKILLS_HOME Path.home() / .agent-skills REGISTRY SKILLS_HOME / registry.json def _load_registry() - dict: if not REGISTRY.exists(): return {skills: {}} return json.loads(REGISTRY.read_text(encodingutf-8)) def _save_registry(registry: dict) - None: SKILLS_HOME.mkdir(parentsTrue, exist_okTrue) REGISTRY.write_text(json.dumps(registry, ensure_asciiFalse, indent2), encodingutf-8) def _git_clone_to_temp(url: str) - str: tmp tempfile.mkdtemp(prefixaskpm-) subprocess.run([git, clone, --depth, 1, url, tmp], checkTrue) return tmp def install(skill_spec: str typer.Argument(..., help仓库链接或 skillversion)): # 1. 解析 spec支持 #main 或 #v1.2.0 形式指定版本 version latest if in skill_spec: skill_spec, version skill_spec.rsplit(, 1) # 2. 拉取仓库到临时目录 tmp_dir _git_clone_to_temp(skill_spec) # 3. 定位 skills 目录下的包 skills_root Path(tmp_dir) / skills package_dirs [p for p in skills_root.iterdir() if p.is_dir()] # 4. 逐个复制到本地并注册 for pkg in package_dirs: meta _read_skill_meta(pkg / SKILL.md) target_dir SKILLS_HOME / skills / meta[name] shutil.copytree(pkg, target_dir, dirs_exist_okTrue) reg _load_registry() reg[skills][meta[name]] { name: meta[name], version: meta[version], source: skill_spec, installed_at: datetime.now().isoformat(), } _save_registry(reg) typer.echo(finstalled {meta[name]}{meta[version]}) # 5. 清理临时目录 shutil.rmtree(tmp_dir, ignore_errorsTrue)这里我故意做了简化安装时直接 clone 整个源仓库。实际使用中当仓库很大或只需要安装其中一两个包时可以改用 sparse checkout 或直接下载 GitHub/Gitea 的 archive 链接。但核心逻辑不变解析链接、定位包、复制落盘、登记注册。安装完成后的目录结构是这样~/.agent-skills/ ├── registry.json └── skills/ ├── web-extractor/ └── html-cleaner/Agent 工具那边只需要把 Skills 目录指向~/.agent-skills/skills就能统一发现并加载这些 Skill运行时根本不需要关心安装过程的细节。3.4 update/list/remove 三个常用子命令有了注册表update的逻辑就非常顺理成章读取注册表里每个 Skill 的source重新拉取最新代码比对SKILL.md里的版本号有变化就覆盖更新并把新版本号写回注册表。app.command() def update(name: str typer.Argument(None, helpSkill 名称缺省更新全部)): reg _load_registry() targets [name] if name else list(reg[skills].keys()) for skill_name in targets: info reg[skills].get(skill_name) if not info: typer.echo(fnot installed: {skill_name}) continue install(f{info[source]}) typer.echo(fupdated {skill_name})list命令就是在注册表上做一个格式化输出把名称、版本、来源三列打印出来remove则是在删除目录的同时从注册表移除对应条目。这部分没有技术难度但它是让整个工具具备“状态可追踪”能力的关键缺了它这就不叫包管理器只是一个下载脚本。4. 实际运行阶段踩过的坑与排查实录4.1 链接格式不稳定Raw 链接和分支名的坑我最早踩的一个坑是不同代码托管平台的 Raw 链接规则不统一。GitHub 的 raw 链接是raw.githubusercontent.com/user/repo/main/pathGitee 是gitee.com/user/repo/raw/main/pathGitLab 又是另一种结构。如果你在写安装器时默认“所有链接都能直接用 requests 下载”很快就会遇到 404。更隐蔽的坑是分支名。很多仓库默认分支已经从master改成了main但老的链接文档里还写着master安装时直接失败。我的处理方式是在解析链接时不把分支名写死而是先用 Git 命令探测origin/HEAD再拼原始链接。另外凡是涉及 Raw 链接的场景一律优先走仓库提供的 archive 下载接口稳定性会好很多。4.2 安装目录方案复制还是软链接这是一个会直接影响日常使用体验的决策。我一开始为了“改完仓库代码立刻生效”用了软链接方案把本地 Skills 目录里的条目软链接到仓库目录。好处确实是实时同步但坏处也很明显仓库切换到别的分支时软链接可能瞬间指向不存在的文件多人协作时还可能因为路径不同导致链接断裂。后来我改成了默认复制、显式指定才用软链接的策略。复制方案虽然每次更新要多花几秒但它换来的是“安装后所有文件都归于 Agent 目录管理原仓库怎么折腾都不影响运行”。这个取舍生产环境里我认为非常值得。如果确实需要频繁改 Skill 并看效果加一个--link参数手动开启。4.3 依赖与版本冲突的三种处理策略Skill 依赖 Skill 的情况实际比想象中多。比如web-extractor依赖html-cleaner如果html-cleaner更新了接口web-extractor就可能行为异常。我没有去做复杂的依赖解析而是采用三层策略从简单到复杂逐步升级。第一层是版本锁定SKILL.md里声明html-cleaner^1.0.0安装时统一解析成具体版本写入注册表升级需要显式操作避免悄悄升级带来的行为漂移。第二层是随包携带如果一个 Skill 对某个依赖的耦合度太高直接把依赖放进自己目录下的vendor/子目录互不干扰。第三层是命名空间隔离给不同业务线的 Skill 加上不同的前缀或路径段比如team-a.web-extractor和team-b.web-extractor从根上避免同名冲突。按这个顺序95% 的问题都能解决没必要一开始就上重型依赖解析器。4.4 常见问题速查表问题现象可能原因处理办法安装后 Agent 找不到新 Skill工具配置的 Skills 目录没指向~/.agent-skills/skills检查 Agent 配置重启会话加载新技能链接安装时报 404仓库分支名不是main路径大小写不一致先手动访问 Raw 链接确认可访问再重试更新后 Agent 行为异常版本非预期变更用remove后重新安装旧版本或直接从仓库 checkout 旧 tag多台机器 Skill 版本不一致缺少统一锁文件将registry.json纳入版本管理团队以它为准目录里有残留文件导致安装失败上次安装中断副本不完整手动删除~/.agent-skills/skills/对应目录后重装注意整个工具链里最容易被忽视的是“安装过程的原子性”。我建议安装时先写到临时目录全部成功后再重命名成正式目录。如果复制到一半崩溃残留的半个 Skill 可能导致 Agent 加载失败。5. 还可以往哪个方向扩展这套包管理器目前已经稳定覆盖了我的日常场景但还有几个方向我实际也在用顺便分享出来。其一是离线导出把安装好的 Skill 目录连同 registry 一起打包传到内网机器就能离线安装对封闭开发环境特别有用。其二是私有源在 Gitea 或 Gogs 上建一个 internal 仓库把团队几个核心 Skill 推上去客户端通过配置多个源就能同时从官方仓库和内部仓库拉取这个思路跟 Docker 镜像仓库非常像。其三是与 CI/CD 结合设置一个定时任务每天自动检查源仓库里的 Skill 是否有新版本若有则自动构建出更新日志形成简单的变更周报。我个人在实际操作中的体会是这套东西真正改变的不是“安装 Skill”这个动作本身而是让我开始用工程化思维去对待 AI 能力沉淀这件事。以前 Skill 是散装的经验文档是“写完了谁找到算谁的”现在它是带版本、带来源、带依赖的生命周期产物是团队可以共同维护的基础设施。整个链条里最关键的其实只有两个约定仓库目录必须规范注册表必须可信。这两条守住了后面的安装、更新、排查都会顺很多。这套方案我从头到尾没有做“大一统平台”也刻意没有加入复杂权限控制和服务端组件一个 CLI 一个 Git 仓库已经能解决 80% 的问题。如果你正在为 Skill 数量增长而头痛不妨也先用这套思路搭个最简版本跑通之后再按自己的习惯去打磨。
Agent Skill 包管理器：用 Git 仓库与链接实现工程化技能管理
手头攒了 120 多个 Agent Skill 之后我彻底放弃了“手动管理”这条路。早期只有十几个 Skill 时复制粘贴、改改路径还算能撑住后来仓库越拉越多、大家各改各的版本光是核对“当前这个 Skill 到底是哪个仓库来的、版本对不对”就能耗掉半天。我最后造了一套极简的方案把仓库当作源把链接当作安装指令一条命令完成 Skill 的安装、更新和卸载底层思路跟 npm、pip 几乎一模一样只不过这次“安装”的对象是 AI Agent 的技能包。这篇就把这套“Agent Skill 包管理器”的设计思路、实现细节和踩坑实录完整拆开讲一遍。先说清楚这套东西适合谁看。如果你在折腾 Claude Code、Cursor 这类支持 Skill/Agent 机制的 AI 编程工具或者正在给自己团队的 Agent 沉淀一套可复用的技能库又恰好被“Skill 数量一多就乱成一团”这件事困扰那这篇文章很适合你。如果你还在十几二十个 Skill 的规模看完至少能提前避开后面几个大坑。1. 为什么 Agent Skill 也需要一套“包管理器”1.1 先分清三个容易混的概念Agent、Skill、MCP很多刚接触这块的人会把 Agent、Skill、MCP 搅在一起实际它们是三个不同层级的东西。MCPModel Context Protocol解决的是 Agent 如何标准化地调用外部工具和数据源它是偏底层的“接口协议”。你写一个 MCP server本质上是在给 AI 提供一套可被统一发现、统一调用的工具入口。Skill 解决的是 Agent 遇到某类任务时如何组织自己的思考流程、调用哪些工具、按什么顺序执行它更偏“经验沉淀”。Agent 则是一个能自主规划、拆解任务并持续执行的角色单位。我常打的比方是MCP 像墙上的标准插座负责供电协议统一Skill 像你脑子里的“遇到这种情况就走这套流程”的肌肉记忆Agent 是把所有这些组装起来的那个“人”。所以 Skill 是比 Agent 更小的复用粒度一个 Agent 可以挂载十几个 Skill一个 Skill 也可以被不同 Agent 复用。1.2 Skill 数量过百之后手工管理会崩在哪里我最初管理 Skill 的方式极其原始建一个公共目录每个 Skill 一个文件夹改动就直接改文件。这个模式在 20 个以内还能凑合一旦超过 50 个四个问题会接踵而至。第一个是“版本漂移”。同一个 Skill 在不同机器、不同项目里的版本不一致A 同事改了一个文件B 同事完全不知道最后大家调同一个 Agent 行为却不一样。第二个是“来源失忆”。三个月前从某个仓库拉来的 Skill再想找原始出处时已经记不清了后续维护只能靠猜。第三个是“依赖地狱”。一部分 Skill 会依赖另外的公共 Skill 或模板手工管理时完全没有任何依赖声明装漏了只能运行时报错才发现。第四个是“上手成本”。新同学加入项目想配齐环境得靠口头交接、文档手把手拷贝效率低到离谱。这些痛点传统软件开发领域早就经历过并且已经有成熟解法那就是包管理器。1.3 软件包管理器的思路迁移想想我们日常是怎么用包管理器的。Python 用 pip 或 uv 从 PyPI 拉包前端用 npm 从 registry 拉依赖Maven 项目要配中央仓库或镜像仓库Docker 镜像也有 registry 的概念。这些工具的共同点是有一个明确的“源”包有规范的元数据安装动作可以通过一条命令完成并且支持版本管理。那 Agent Skill 为什么不能照搬这套完全能搬。我把 Skill 看成一种特殊的“软件包”把 Git 仓库当成“源”把一条可解析的资源链接当成“安装指令”于是就有了这套非常轻量的包管理器。核心就三句话仓库是源链接是安装清单文件管版本。这套设计最大的价值不是炫技而是让 Skill 管理从一个“靠自觉的文件夹整理问题”变成一个“有标准可依的工程问题”。接下来我详细展开架构上的几个关键选择。2. 这套方案的整体架构“仓库是源链接是安装”2.1 核心抽象把 Skill 当成“可安装的软件包”在设计之前我先定义清楚 Skill 包的最小单元长什么样。一个 Skill 包就是一个包含标准元数据的目录里面必须有SKILL.md文件用来描述这个 Skill 的名称、版本、功能、依赖和入口说明。类比的话SKILL.md就是软件包的package.json或pyproject.toml是整个包管理逻辑的锚点。目录里可以再带辅助资源比如脚本、模板、参考文档它们都算这个 Skill 包的“内容文件”。安装一个 Skill本质上就是把一个远程目录完整地复制到本地某个约定好的 Skills 目录里并在一个全局注册表文件里登记这条记录。为什么必须搞一个注册表文件因为只复制目录是不够的你还需要回答“当前装了哪些包、各自什么版本、来自哪个仓库、升级到哪个版本了”。这些数据用一个 JSON 或 YAML 清单来持久化是整套系统能够追踪状态的基础。2.2 源层设计仓库目录规范与索引文件源选什么我实测下来用 Git 仓库做源是成本最低、最通用的方案。你可以用 GitHub、GitLab、Gitee也可以用自建的 Gitea/Gogs 内部仓库。关键是仓库内部的目录结构要有规范我的推荐结构如下skills-repo/ ├── index.yaml ├── README.md └── skills/ ├── web-extractor/ │ ├── SKILL.md │ ├── scripts/ │ │ └── extract.py │ └── assets/ │ └── prompt-template.md ├── code-reviewer/ │ ├── SKILL.md │ └── templates/ │ └── review-check.md └── html-cleaner/ ├── SKILL.md └── ...index.yaml是源仓库的索引文件相当于软件源的“仓库元数据”。它记录这个源里有哪些包、每个包的最新版本和路径这样客户端可以只拉索引、不拉全仓就能搜索和比对版本。source: https://github.com/example/skills-repo updated: 2025-06-01 packages: - name: web-extractor version: 1.2.0 path: skills/web-extractor description: 从任意网址提取正文并整理为结构化 Markdown - name: code-reviewer version: 0.9.1 path: skills/code-reviewer description: 基于提交记录生成代码评审意见索引文件不强制复杂化能支持“列出所有包”和“定位指定包路径”这两个操作就够用。具体包内的SKILL.md负责描述自身详情索引文件只做轻量登记避免双份维护带来的信息不同步。2.3 安装层设计链接解析、拉取与落盘注册这一层是整套系统的发动机核心任务是把一条链接变成一次安装。我的“链接”约定有几种形式按优先级排列https://github.com/user/skills-repo//skills/web-extractor这种带//的写法表示仓库内的子目录路径这是最常用的形式。https://github.com/user/skills-repo/archive/refs/tags/v1.2.0.tar.gz这种指向压缩包的链接适合脱离 Git 元数据直接安装某次 release。https://gitee.com/user/skills-repo/raw/main/skills/xxx这种 Raw 文件链接适合安装单文件形态的轻量 Skill。安装流程拆成五步解析链接、拉取内容、校验完整性、落盘、注册。每一步都有坑我在第 4 节专门讲。这里先给一个简化版的 Python 实现思路完整代码后面会展示。3. 动手实现写一个简版 Skill 包管理器3.1 环境准备为什么我用 Python uv 搭这个工具我最后实现的时候选了 Python配 uv 做环境和依赖管理。选 Python 的原因很简单跨平台、写 CLI 顺手、团队里懂的人多。选 uv 而不是直接用 pip是因为 uv 创建虚拟环境和安装依赖的速度确实快一条uv sync就把环境全部搞定适合这种需要快速分发的小工具。初始化项目的命令如下uv init askpm cd askpm uv add typer requests uv add --dev pytesttyper用来写命令行参数解析比手写argparse舒服很多自动生成--help还能直接基于函数签名做参数校验。命名上我起名askpm也就是 Agent Skill Package Manager 的缩写方便后面称呼。3.2 SKILL.md 元数据规范与索引生成一个标准的SKILL.md长这样开头用 YAML frontmatter 写元数据--- name: web-extractor version: 1.2.0 description: 从任意网址提取正文并整理为结构化 Markdown author: exampleexample.com license: MIT entry: SKILL.md dependencies: - html-cleaner^1.0.0 tags: [web, extraction] --- # Web Extractor 当用户需要提取网页正文时按以下步骤执行 1. 打开目标网址。 2. 用内置脚本提取正文。 3. 去掉导航、广告等噪声内容。 4. 输出结构化 Markdown。注意dependencies字段它声明这个 Skill 运行需要哪些其他 Skill。这个字段在手工管理阶段纯靠人肉记忆有了它包管理器就能在安装时自动先装依赖项。entry指定 Agent 应该读取哪个文件作为 Skill 的完整定义大多数情况下就是SKILL.md本身。索引文件不需要手写可以用脚本扫描仓库自动生成。核心逻辑就是遍历skills/目录读取每个子目录下SKILL.md的 frontmatter然后汇总成index.yaml。这样源仓库维护者只需要维护每个包的元数据索引永远和实际目录一致。3.3 install 命令的实现链接到安装的完整流转install是整套工具的核心命令我直接给出一个可运行的简化实现方便你理解全链路逻辑# askpm/install.py from pathlib import Path import hashlib import json import tempfile import subprocess import shutil import typer SKILLS_HOME Path.home() / .agent-skills REGISTRY SKILLS_HOME / registry.json def _load_registry() - dict: if not REGISTRY.exists(): return {skills: {}} return json.loads(REGISTRY.read_text(encodingutf-8)) def _save_registry(registry: dict) - None: SKILLS_HOME.mkdir(parentsTrue, exist_okTrue) REGISTRY.write_text(json.dumps(registry, ensure_asciiFalse, indent2), encodingutf-8) def _git_clone_to_temp(url: str) - str: tmp tempfile.mkdtemp(prefixaskpm-) subprocess.run([git, clone, --depth, 1, url, tmp], checkTrue) return tmp def install(skill_spec: str typer.Argument(..., help仓库链接或 skillversion)): # 1. 解析 spec支持 #main 或 #v1.2.0 形式指定版本 version latest if in skill_spec: skill_spec, version skill_spec.rsplit(, 1) # 2. 拉取仓库到临时目录 tmp_dir _git_clone_to_temp(skill_spec) # 3. 定位 skills 目录下的包 skills_root Path(tmp_dir) / skills package_dirs [p for p in skills_root.iterdir() if p.is_dir()] # 4. 逐个复制到本地并注册 for pkg in package_dirs: meta _read_skill_meta(pkg / SKILL.md) target_dir SKILLS_HOME / skills / meta[name] shutil.copytree(pkg, target_dir, dirs_exist_okTrue) reg _load_registry() reg[skills][meta[name]] { name: meta[name], version: meta[version], source: skill_spec, installed_at: datetime.now().isoformat(), } _save_registry(reg) typer.echo(finstalled {meta[name]}{meta[version]}) # 5. 清理临时目录 shutil.rmtree(tmp_dir, ignore_errorsTrue)这里我故意做了简化安装时直接 clone 整个源仓库。实际使用中当仓库很大或只需要安装其中一两个包时可以改用 sparse checkout 或直接下载 GitHub/Gitea 的 archive 链接。但核心逻辑不变解析链接、定位包、复制落盘、登记注册。安装完成后的目录结构是这样~/.agent-skills/ ├── registry.json └── skills/ ├── web-extractor/ └── html-cleaner/Agent 工具那边只需要把 Skills 目录指向~/.agent-skills/skills就能统一发现并加载这些 Skill运行时根本不需要关心安装过程的细节。3.4 update/list/remove 三个常用子命令有了注册表update的逻辑就非常顺理成章读取注册表里每个 Skill 的source重新拉取最新代码比对SKILL.md里的版本号有变化就覆盖更新并把新版本号写回注册表。app.command() def update(name: str typer.Argument(None, helpSkill 名称缺省更新全部)): reg _load_registry() targets [name] if name else list(reg[skills].keys()) for skill_name in targets: info reg[skills].get(skill_name) if not info: typer.echo(fnot installed: {skill_name}) continue install(f{info[source]}) typer.echo(fupdated {skill_name})list命令就是在注册表上做一个格式化输出把名称、版本、来源三列打印出来remove则是在删除目录的同时从注册表移除对应条目。这部分没有技术难度但它是让整个工具具备“状态可追踪”能力的关键缺了它这就不叫包管理器只是一个下载脚本。4. 实际运行阶段踩过的坑与排查实录4.1 链接格式不稳定Raw 链接和分支名的坑我最早踩的一个坑是不同代码托管平台的 Raw 链接规则不统一。GitHub 的 raw 链接是raw.githubusercontent.com/user/repo/main/pathGitee 是gitee.com/user/repo/raw/main/pathGitLab 又是另一种结构。如果你在写安装器时默认“所有链接都能直接用 requests 下载”很快就会遇到 404。更隐蔽的坑是分支名。很多仓库默认分支已经从master改成了main但老的链接文档里还写着master安装时直接失败。我的处理方式是在解析链接时不把分支名写死而是先用 Git 命令探测origin/HEAD再拼原始链接。另外凡是涉及 Raw 链接的场景一律优先走仓库提供的 archive 下载接口稳定性会好很多。4.2 安装目录方案复制还是软链接这是一个会直接影响日常使用体验的决策。我一开始为了“改完仓库代码立刻生效”用了软链接方案把本地 Skills 目录里的条目软链接到仓库目录。好处确实是实时同步但坏处也很明显仓库切换到别的分支时软链接可能瞬间指向不存在的文件多人协作时还可能因为路径不同导致链接断裂。后来我改成了默认复制、显式指定才用软链接的策略。复制方案虽然每次更新要多花几秒但它换来的是“安装后所有文件都归于 Agent 目录管理原仓库怎么折腾都不影响运行”。这个取舍生产环境里我认为非常值得。如果确实需要频繁改 Skill 并看效果加一个--link参数手动开启。4.3 依赖与版本冲突的三种处理策略Skill 依赖 Skill 的情况实际比想象中多。比如web-extractor依赖html-cleaner如果html-cleaner更新了接口web-extractor就可能行为异常。我没有去做复杂的依赖解析而是采用三层策略从简单到复杂逐步升级。第一层是版本锁定SKILL.md里声明html-cleaner^1.0.0安装时统一解析成具体版本写入注册表升级需要显式操作避免悄悄升级带来的行为漂移。第二层是随包携带如果一个 Skill 对某个依赖的耦合度太高直接把依赖放进自己目录下的vendor/子目录互不干扰。第三层是命名空间隔离给不同业务线的 Skill 加上不同的前缀或路径段比如team-a.web-extractor和team-b.web-extractor从根上避免同名冲突。按这个顺序95% 的问题都能解决没必要一开始就上重型依赖解析器。4.4 常见问题速查表问题现象可能原因处理办法安装后 Agent 找不到新 Skill工具配置的 Skills 目录没指向~/.agent-skills/skills检查 Agent 配置重启会话加载新技能链接安装时报 404仓库分支名不是main路径大小写不一致先手动访问 Raw 链接确认可访问再重试更新后 Agent 行为异常版本非预期变更用remove后重新安装旧版本或直接从仓库 checkout 旧 tag多台机器 Skill 版本不一致缺少统一锁文件将registry.json纳入版本管理团队以它为准目录里有残留文件导致安装失败上次安装中断副本不完整手动删除~/.agent-skills/skills/对应目录后重装注意整个工具链里最容易被忽视的是“安装过程的原子性”。我建议安装时先写到临时目录全部成功后再重命名成正式目录。如果复制到一半崩溃残留的半个 Skill 可能导致 Agent 加载失败。5. 还可以往哪个方向扩展这套包管理器目前已经稳定覆盖了我的日常场景但还有几个方向我实际也在用顺便分享出来。其一是离线导出把安装好的 Skill 目录连同 registry 一起打包传到内网机器就能离线安装对封闭开发环境特别有用。其二是私有源在 Gitea 或 Gogs 上建一个 internal 仓库把团队几个核心 Skill 推上去客户端通过配置多个源就能同时从官方仓库和内部仓库拉取这个思路跟 Docker 镜像仓库非常像。其三是与 CI/CD 结合设置一个定时任务每天自动检查源仓库里的 Skill 是否有新版本若有则自动构建出更新日志形成简单的变更周报。我个人在实际操作中的体会是这套东西真正改变的不是“安装 Skill”这个动作本身而是让我开始用工程化思维去对待 AI 能力沉淀这件事。以前 Skill 是散装的经验文档是“写完了谁找到算谁的”现在它是带版本、带来源、带依赖的生命周期产物是团队可以共同维护的基础设施。整个链条里最关键的其实只有两个约定仓库目录必须规范注册表必须可信。这两条守住了后面的安装、更新、排查都会顺很多。这套方案我从头到尾没有做“大一统平台”也刻意没有加入复杂权限控制和服务端组件一个 CLI 一个 Git 仓库已经能解决 80% 的问题。如果你正在为 Skill 数量增长而头痛不妨也先用这套思路搭个最简版本跑通之后再按自己的习惯去打磨。
