agentic-awesome-skills 稳定技能清单Stable Skills Manifest v1自定义宿主集成与懒加载接入指南【免费下载链接】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_index.json即 Stable Skills Manifest v1展开它是自定义宿主Custom Host集成与懒加载器Lazy Loader使用的「遗留兼容」公开契约一个 JSON 数组每个技能对应一个条目用于在不加载任何SKILL.md正文的前提下完成技能发现、skill-id解析与按需读取。读完本文你将掌握该清单的完整字段契约、Schema 约束、data/镜像同步规则以及一条「读清单 → 解析 ID → 懒加载单文件 → 限制每轮上限 → 路径安全校验」的官方推荐集成路径并理解它与 AAS Core面向 Codex / Claude Code 的本地只读 MCP 目录之间的边界。适用前提本契约面向没有 AAS Core 宿主适配器的自定义集成例如 Jetski/Cortex 风格的宿主。Codex 与 Claude Code 用户应优先使用 AAS Core而不是直接把宿主直连仓库清单。1. Manifest v1 契约总览清单的稳定契约可以概括为以下四点完整定义见 discovery-manifest.md契约项内容规范文件仓库根目录的skills_index.json镜像文件data/skills_index.json必须是根清单的精确兼容镜像exact compatibility mirror格式JSON 数组每个技能一个对象Schemaschemas/skills-index.v1.schema.json从仓库实际状态看当前根清单与镜像均为 52,540 行、2,124 个技能条目且两份文件内容完全一致可用diff -q skills_index.json data/skills_index.json验证。这一点也印证了文档中「两者载荷相同」的稳定约定。1.1 为什么需要一份「稳定清单」仓库实际包含 2,000 个技能目录仅skills/目录下就有数百个以SKILL.md为核心的技能子目录如果宿主在启动时把每一个SKILL.md都读进上下文模型上下文窗口会被瞬间占满并触发类似 Jetski/Cortex 宿主常见的错误TrajectoryChatConverter: could not convert a single message before hitting truncation稳定清单的价值在于用一份轻量 JSON 数组替代全量正文扫描让宿主只根据对话中出现的skill-id按需读取对应技能正文。这不是 AAS Core 的目录或栈生命周期契约后者由 aas-core.md 定义而是面向自定义多技能宿主的上下文截断与轨迹转换错误的主要预防手段。2. 必填字段与 Schema 约束2.1 必填字段每个清单条目包含以下字段discovery-manifest.md 中明确定义字段含义id技能标识符与skill-id一致path相对技能目录例如skills/brainstormingcategory用于 UI / 搜索表面的分组name显示名称description简短用途 / 触发摘要risk仓库风险标签之一source权威 / 信任元数据的来源date_addedISO 日期字符串或null此外允许附加字段如tagsplugin元数据为可选项。从根清单统计看当前 2,124 个条目中risk分布为critical1,101、safe859、none103、offensive61source以community1,399为主另有official、personal、self以及大量标注了上游仓库来源的条目有 444 个条目带tags字段且所有条目当前都带有plugin元数据date_added均非null。这些统计可直接用于宿主侧的 UI 过滤或展示。2.2 Schema 的强制约束schemas/skills-index.v1.schema.json 将契约落到可验证的 JSON Schemadraft 2020-12上顶层必须是array每个条目必须包含上述 8 个必填字段缺任一字段即校验失败id、category、name、risk、source均要求minLength: 1非空字符串path必须以^skills/开头保证条目路径不会指向仓库技能目录之外description为任意字符串date_added允许string或nullplugin为可选对象内部含targetscodex/claude等目标到状态字符串的映射、setup任意附加配置对象与reasons字符串数组additionalProperties: true意味着额外字段如tags合法。以文档给出的完整示例条目为准discovery-manifest.md{ id: brainstorming, path: skills/brainstorming, category: planning, name: brainstorming, description: Use before any creative or constructive work., risk: safe, source: official, date_added: 2026-02-27 }注意仓库中实际存在的 skills/brainstorming/SKILL.md 的 frontmatter 为risk: critical、source: community说明文档示例是「结构示意」真实条目以清单文件当前内容为准——这也提醒集成方清单是运行时的事实来源不要硬编码任何单条技能的风险或来源值。3. 推荐的宿主行为清单驱动的懒加载稳定集成绝不能在启动时加载全部技能指令文件。官方推荐的宿主行为discovery-manifest.md是读取清单skills_index.json一次只解析对话中出现的skill-id对每个解析出的技能懒加载对应的那一个SKILL.md施加每轮per-turn技能数量上限避免用户提示超出上下文限制校验每个解析出的路径都落在你配置的SKILLS_ROOT之内。其中第 4、5 步正是「上下文截断与轨迹转换错误」在自定义多技能宿主中的主要预防手段。3.1 完整参考实现Jetski Gemini 懒加载器仓库在 docs/integrations/jetski-gemini-loader/README.md 提供了一个最小参考实现其核心模块 loader.mjs 将上述 5 步拆成了可复用的四个导出函数函数职责loadSkillIndex(indexPath)启动时读取清单构建id - SkillMeta的MapresolveSkillsFromMessages(messages, index, maxSkills)扫描消息中的skill-id并解析为元数据受maxSkills限制loadSkillBodies(skillsRoot, metas)按路径读取SKILL.md正文含路径逃逸校验buildModelMessages({...})组装[基础 system 消息 每个选中技能的 system 消息 轨迹]3.1.1 启动引导与 ID 解析const SKILL_ID_REGEX /([a-zA-Z0-9-_./])/g; export function loadSkillIndex(indexPath) { const raw fs.readFileSync(indexPath, utf8); const arr JSON.parse(raw); const map new Map(); for (const meta of arr) { map.set(meta.id, meta); } return map; } export function resolveSkillsFromMessages(messages, index, maxSkills) { const referencedSkillIds new Set(); for (const msg of messages) { for (const match of msg.content.matchAll(SKILL_ID_REGEX)) { const id match[1]; if (index.has(id)) referencedSkillIds.add(id); } } const metas []; for (const id of referencedSkillIds) { const meta index.get(id); if (meta) metas.push(meta); if (metas.length maxSkills) break; } return metas; }要点正则([a-zA-Z0-9-_./])支持带连字符、点、斜杠的技能 ID 形态只在清单中存在的 ID 才会被收集index.has(id)maxSkills必须为正整数assertValidMaxSkills会拒绝非整数或 1的值。3.1.2 懒加载与路径安全源码级细节loadSkillBodies是路径安全的重点loader.mjs其防御手段可归纳为三层相对路径逃逸校验对path.resolve(skillsRoot, meta.path)计算相对路径若以..开头或为绝对路径则抛错Skill path escapes skills root符号链接拒绝技能目录与SKILL.md都必须是通过lstat确认的普通目录 / 普通文件任何符号链接都会被拒绝realpath 二次校验读取前先realpath解析最终目标再次确认其仍位于SKILLS_ROOT之内防止目录内软链绕出。这直接对应文档中「Validate each resolved path stays under your configuredSKILLS_ROOT」的要求也解释了为什么推荐集成必须把路径安全当作硬约束而非可选项。3.1.3 组装模型消息与溢出策略export async function buildModelMessages(options) { const { baseSystemMessages, trajectory, skillIndex, skillsRoot, maxSkillsPerTurn 8, overflowBehavior truncate, } options; const referencedSkillIds collectReferencedSkillIds(trajectory, skillIndex); if (overflowBehavior error referencedSkillIds.length maxSkillsPerTurn) { throw new Error( Too many skills requested in a single turn. Reduce skill-id usage to ${maxSkillsPerTurn} or fewer., ); } const selectedMetas resolveSkillsFromMessages(trajectory, skillIndex, maxSkillsPerTurn); if (selectedMetas.length 0) { return [...baseSystemMessages, ...trajectory]; } const skillBodies await loadSkillBodies(skillsRoot, selectedMetas); const skillMessages skillBodies.map((body) ({ role: system, content: body })); return [...baseSystemMessages, ...skillMessages, ...trajectory]; }默认参数与语义maxSkillsPerTurn默认8文档与 Jetski 指南建议的实用范围是 5–10overflowBehavior默认truncate静默截断到上限设为error时若单轮引用数超过上限会直接抛错适合希望「明确失败而非静默丢失技能」的宿主无任何skill-id引用时buildModelMessages原样返回[基础消息 轨迹]不产生额外开销。典型调用示例TypeScript 伪代码见 jetski-gemini-loader READMEconst REPO_ROOT /path/to/agentic-awesome-skills; const SKILLS_ROOT REPO_ROOT; const INDEX_PATH path.join(REPO_ROOT, skills_index.json); const skillIndex loadSkillIndex(INDEX_PATH); // 1. 启动时引导一次 const modelMessages await buildModelMessages({ baseSystemMessages, trajectory, skillIndex, skillsRoot: SKILLS_ROOT, maxSkillsPerTurn: 8, overflowBehavior: error, }); // 2. 将 modelMessages 交给 Jetski/Cortex Gemini 客户端该示例是最小参考而非生产级库实际宿主应在接入TrajectoryChatConverter的位置挂载buildModelMessages并按需补充 token 计数 / 截断逻辑、更严格的安全预算。4. 为什么要保留data/镜像data/skills_index.json的存在是为了下游兼容部分客户端仍从data/子树读取。稳定的契约是两份文件载荷完全相同discovery-manifest.md。对集成方而言这意味着新集成优先读根目录skills_index.json仅当宿主明确从data/读取时才把data/skills_index.json作为兼容读取路径不要把两份文件当作可能分叉的独立数据源——它们必须保持一致。5. 与 AAS Core 的边界清单契约明确强调它不是AAS Core 目录或栈生命周期契约discovery-manifest.md。两者的分工如下维度Stable Skills Manifest v1本文主题AAS Core面向宿主无 AAS Core 适配器的自定义集成 / 懒加载器Codex、Claude Code暴露方式原始 JSON 清单 手动懒加载本地只读 MCP 工具search_skills、get_skill、compose_stack等核心能力技能发现 按需读取完整本地目录检索、agent 自主选型、栈校验与规划上下文保护宿主自行实现 per-turn 上限与SKILLS_ROOT校验只读、按需返回技能正文标记为不可信内容需要说明的是AAS Core 的完整能力含compose_stack、inspect_stack、diff_stack、证据导出等属于 aas-core.md 的范围本文不展开自定义集成方应判断自己是否有 AAS Core 宿主适配器若有则优先走 AAS Core而不是直连仓库清单。6. 集成中的上下文溢出与边界场景6.1 溢出处理策略参考 jetski-cortex.md 的建议宿主应同时设置两类阈值安全阈值例如上下文窗口的 70%–80%每轮技能数量上限例如 5–10 个。当阈值被触发时两种策略二选一减少纳入的技能例如按最近引用或优先级取舍向用户返回明确错误例如Too many skills were requested in a single turn. Reduce the number ofskill-idreferences in your message or split them into multiple turns.6.2 推荐的验证场景场景 1普通消息消息不含skill-id→ 不加载任何SKILL.md→ prompt 保持精简 → 无错误场景 2少量技能消息含 1–2 个skill-id→ 仅加载对应SKILL.md→ 无溢出场景 3大量技能消息含大量skill-id→maxSkillsPerTurn或 token 护栏触发 → 不出现静默溢出。6.3 Windows 崩溃循环恢复若宿主如 Antigravity 或 Jetski/Cortex 集成在 Windows 上因截断错误陷入重启循环TrajectoryChatConverter: could not convert a single message before hitting truncation完整恢复步骤见 windows-truncation-recovery.md核心思路是备份%USERPROFILE%\.gemini\antigravity-browser-profile\Default、%AppData%\antigravity等→ 移除问题技能 / 包 → 清理 Local/Session Storage 与%TEMP%→ 以「懒加载 显式上限」重启。预防复发的关键是优先overflowBehavior: error并持续校验解析路径位于skillsRoot内。6.4 技能子集与 Bundles 的进一步控制如果希望进一步收敛加载范围可参考 jetski-cortex.md 与 bundles.md将不必要的技能移入skills/.disabled/在特定环境中排除它们使用仓库的 bundles见 data/bundles.json、data/editorial-bundles.json只加载聚焦的技能分组。7. 快速接入清单Checklist步骤动作依据1启动时读取根skills_index.json构建id - meta映射discovery-manifest.md2若宿主从data/读取确认data/skills_index.json与根清单一致discovery-manifest.md3用([a-zA-Z0-9-_./])扫描消息中的skill-idloader.mjs4只对命中 ID 懒加载path/SKILL.mdloader.mjs5设置maxSkillsPerTurn建议 5–10并选择truncate/errorjetski-cortex.md6校验路径不逃逸SKILLS_ROOT相对路径 符号链接 realpath 三层loader.mjs7用 skills-index.v1.schema.json 校验清单discovery-manifest.md8有 AAS Core 适配器时优先走 AAS Core而非直连清单aas-core.md8. 总结skills_index.json是 agentic-awesome-skills 面向自定义宿主暴露的稳定发现契约8 个必填字段 可选的plugin/ 附加字段配套 JSON Schema 可验证根清单与data/镜像保持完全一致。它的正确使用方式不是「全量注入」而是清单驱动 按skill-id懒加载 每轮上限 SKILLS_ROOT路径安全——这正是自定义多技能宿主避免上下文截断与轨迹转换错误的关键。仓库中的 loader.mjs 提供了可直接借鉴的四函数参考实现若你的目标是 Codex 或 Claude Code则请转向 AAS Core让 Core 完成目录检索、选型校验与可复现的规划闭环。相关文档AAS CoreAgent-Owned Skill StacksJetski/Cortex Gemini 集成指南Jetski Gemini 懒加载器参考实现Windows 截断崩溃循环恢复Skills Index v1 Schema根清单 skills_index.json 与 镜像 data/skills_index.json【免费下载链接】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），仅供参考