agentic-awesome-skills 技能目录刷新完全指南：本地 Catalog 重建、索引生成与维护者同步流程

agentic-awesome-skills 技能目录刷新完全指南本地 Catalog 重建、索引生成与维护者同步流程【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本指南面向 agentic-awesome-skills 仓库的维护者与深度使用者完整讲解如何基于本仓库的skills/权威源重建本地技能目录catalog、仅刷新skills_index.json索引、使用 Windows 启动器拉起本地 Web 应用以及维护者在合并源码后如何正确对待生成产物、规避 CI 漂移。读完你将掌握从git pull到本地目录可用的完整操作链并理解索引生成与 Web 资产同步的底层实现。本地目录的构建链路从权威源到可检索索引在动手执行任何命令之前先明确一个核心前提本地目录local catalog是从本仓库检出的skills/权威源构建出来的。重新生成索引不会拉取新的上游技能也不会发布网站。从 package.json 的scripts定义可以看到整条生成链路的编排validate运行tools/scripts/validate_skills.py做技能规范性校验plugin-compat:sync运行tools/scripts/plugin_compatibility.py同步插件兼容性报告index运行tools/scripts/generate_index.py生成skills_index.jsonbundles:sync运行tools/scripts/sync_editorial_bundles.py同步编辑精选包sync:metadata同步仓库元数据catalog运行tools/scripts/build-catalog.js构建data/catalog.jsonbuild:aas-v1-catalog构建离线 AAS v1 目录这些步骤由chain串联而npm run build就是chain的别名。因此索引与目录是派生产物derived artifacts它们的唯一事实来源是skills/下的技能源文件——每个技能目录下的SKILL.md及其 YAML frontmatter。理解了这一点就能明白为什么原文档反复强调仅刷新索引 ≠ 完整构建。刷新前置准备Node、Python 依赖与干净检出执行任何生成命令前需满足两个环境前提Node 版本必须满足根目录 package.json 中engines声明的node 22Python 依赖生成脚本依赖 tools/requirements.txt 中的pyyaml6.0索引生成器generate_index.py依赖yaml.safe_load解析技能 frontmatter。依赖安装命令# 安装根目录依赖严格按锁文件安装 npm ci # 安装 Web 应用依赖apps/web-app 子项目 npm run app:install在干净的main检出上先获取上游已接受的源码变更且在更新前保存好自己未提交的无关工作git pull --ff-only origin main--ff-only保证快进式更新避免本地意外提交与上游历史分叉。之后就可以执行构建或启动命令。完整刷新npm run build 与 npm run app:dev这是文档推荐的标准刷新路径两条命令各有分工npm run build npm run app:devnpm run build运行完整的校验与生成链即chain技能校验 → 插件兼容性同步 → 索引生成 → 编辑精选包同步 → 元数据同步 → 目录构建 → AAS v1 离线目录构建。它产出根目录的skills_index.json、data/下的目录与兼容性文件npm run app:dev先执行npm run app:setup准备 Web 静态资源再进入apps/web-app启动 Vite 开发服务器。从 setup_web.js 的main()可以看到app:setup具体做了什么把根目录的skills_index.json复制为apps/web-app/public/skills.json同时生成skills.json.backup备份遍历skills/下每个技能的SKILL.md复制到apps/web-app/public/skills/下作为 Web 端可检索的技能正文复制前会做符号链接与越界安全检查copyIndexFile拒绝经符号链接复制索引、拒绝把索引复制到public之外这是 Web 资产准备环节的安全防线。也就是说build决定生成什么app:dev决定把生成物端到本地 Web 服务供检索。仅刷新索引npm run update:skills如果只想更新索引而不做完整构建使用索引专用命令npm run update:skills从 package.json 的脚本定义可见其构成update:skills: node tools/scripts/run-python.js tools/scripts/generate_index.py node tools/scripts/copy-file.js skills_index.json apps/web-app/public/skills.json node tools/scripts/copy-file.js skills_index.json apps/web-app/public/skills.json.backup它做三件事运行tools/scripts/generate_index.py重新生成skills_index.json将其复制为apps/web-app/public/skills.json同时更新skills.json.backup备份副本。注意它不会运行校验、目录构建、精选包同步等完整链路因此不是完整的 bundle/catalog 构建。若你的变更涉及技能源文件本身建议仍走npm run build完整链路。索引生成器源码解读generate_index.py 如何工作若要真正理解本地目录从何而来值得深入 generate_index.py 的实现遍历与发现generate_index()递归遍历skills/目录跳过隐藏目录与符号链接的SKILL.md以包含SKILL.md的目录为单位生成一条技能记录id、path、name、description、risk、source、date_added、plugin等字段frontmatter 解析parse_frontmatter()逐行清洗 YAML对含的未加引号值自动加引号再交给yaml.safe_load解析字段合并时frontmatter 优先于目录推断分类判定分类优先级为 frontmatter 显式category→ 目录结构推断 → 关键词打分推断infer_category对 16 类规则与 family 前缀规则打分低于阈值或得分接近时保守地返回uncategorized→ 最后用CURATED_CATEGORY_OVERRIDES人工覆盖表修正重复 id 防护生成完成后检查重复id存在冲突直接抛ValueError终止生成避免索引中出现歧义条目兼容镜像mirror_canonical_index()会把根目录skills_index.json镜像复制到data/skills_index.json供兼容性消费者使用。这些细节解释了为什么干净检出 权威源是必要条件任何对skills/源文件的损坏、重复 id 或缺失 frontmatter都会在生成阶段暴露出来。Windows 启动器START_APP.bat 的职责边界仓库根目录的 START_APP.bat 是 Windows 下的一键启动入口。从批处理源码看它的实际行为是用WHERE node检查 Node.js 是否安装未安装则报错退出进入apps/web-app检查node_modules是否存在不存在则执行npm install并额外安装supabase/supabase-js若npx vite --version探测失败依赖损坏则删除node_modules重装回到仓库根目录执行npm run app:setup准备技能数据进入apps/web-app用npx -y vite --open启动并自动打开浏览器。需要特别强调的是启动器的职责边界这正是原文档警告的部分它不会执行 Git 拉取更新、不会通过 PowerShell 下载技能、也不会自动安装 Python。因此必须先手动准备好检出与前置依赖Node ≥ 22、Python pyyaml6.0再运行启动器。对于可复现的依赖安装仍然优先使用上文推荐的 npm 命令npm ci、npm run app:install而非启动器内部的npm install。维护者注意事项生成差异、受保护工作流与发布边界生成差异不要混入普通源码 PR更新本地目录后git status会看到一批生成的派生文件如skills_index.json、data/*.json等。这些生成差异应作为证据供审查但不应包含在普通源码 PR 中。这是本仓库的 PR 约定PR 只提交源码变更CI 会把生成产物编辑直接拦截并仅以信息性预览的形式报告漂移详见 ci-drift-fix.md。源码合并后使用受保护的 canonical-sync 工作流源码合并进main之后应使用受保护的 canonical-sync 工作流 来发布生成产物而不是手工提交。该工作流要求main推送后 CI 对漂移是严格失败的仓库必须与生成管线实际产出完全一致修复漂移时运行npm run sync:repo-state做本地规范同步检查git status/git diff若只产生规范生成变更交由受信任的main工作流以automation/canonical-repo-state机器人身份、指定分支与完全可复现的树来发布不要创建普通的人工生成修复 PR若同步后仍有无关或不受管控的漂移必须停下排查机器人只允许发布规范/生成子集。刷新本地目录 ≠ 发布最后记住刷新本地目录的四条边界不更新已安装的技能副本installed skill copies不发布 npm 包不部署 Pages 站点不拉取上游新技能——索引只反映当前检出skills/中已接受的内容。需要向他人分发或部署时走仓库既有的发布流程如 package.json 中的release:publish等脚本而不是依赖本地目录刷新命令。小结一张刷新决策表需求命令产出完整重建校验索引目录npm run buildskills_index.json、data/catalog.json、AAS v1 目录等构建后启动本地 Web 检索npm run app:devVite 服务 apps/web-app/public/资产仅重新生成索引与兼容副本npm run update:skillsskills_index.json、data/skills_index.json、Web 端skills.jsonWindows 一键启动START_APP.bat检查依赖后启动 Vite源码合并后同步规范产物npm run sync:repo-state可提交的规范生成差异走受保护工作流在干净检出上按前置依赖 →npm run build→npm run app:dev的顺序执行即可获得与权威源完全一致的本地技能目录把生成差异留给受保护的同步工作流就能在享受本地检索能力的同时保持main分支的清洁与可复现。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考