如何为 Agent-Skills-for-Context-Engineering 添加一个新技能并跑通全部 CI 校验闸门【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-EngineeringAgent-Skills-for-Context-Engineering 是一个 Agent Skills 集合仓库每个技能是skills/下以SKILL.md为核心的目录仓库自带一套确定性校验闸门在 CI 上对每个 PR 执行。往这个仓库加一个新技能不只是复制一个模板目录——你还必须同步两份插件清单、根目录文档、researcher 语料索引和激活回归测试用例然后依次跑通 CONTRIBUTING.md 列出的全部闸门命令才算完成。本文按创建技能目录 → 注册到清单与索引 → 跑闸门的路径给出每一步的硬约束和每道闸门的通过判据所有规则均取自各校验脚本的实际实现。适用对象准备向本仓库提交新技能的贡献者。全部命令都在仓库根目录执行要求环境中已有 Python 3 和 pip。准备条件先在仓库根目录安装校验依赖python3 -m pip install -r requirements-dev.txt该命令会把 requirements-dev.txt 中的pyyaml和skills-ref装入当前 Python 环境。skills-ref提供上游agentskillsCLI平台兼容闸门下文第 2 道会调用它pyyaml是严格 YAML 解析的前置依赖。按模板创建技能目录把 template/SKILL.md 复制为skills/新技能名/SKILL.md需要时再建可选的references/和scripts/目录。README 给出的目录规范是skill-name/ ├── SKILL.md # Required: instructions metadata ├── scripts/ # Optional: executable code demonstrating concepts └── references/ # Optional: additional documentation and resources新技能名在下文统一指你新建的目录名。下面这些约束由 validate_repo.py 逐条强制执行违反任意一条都会以 error 报出命名frontmatter 的name必须与目录名一致且为小写 kebab-case正则[a-z0-9](?:-[a-z0-9])*不允许连续连字符。description必须存在、不超过 1024 字符、用引号包裹。出现I can、Use me、You can use this会被判为非第三人称——这是一条 warning但在--strict模式下 warning 同样导致闸门失败所以必须写成第三人称。长度SKILL.md正文不得超过 500 行超长内容移入references/。必选章节以下 8 个 H2 一个都不能少——## When to Activate、## Core Concepts、## Practical Guidance、## Examples、## Guidelines、## Gotchas、## Integration、## References。激活边界正文需包含 Do not activate 字样为相邻技能划出边界模板给出的格式示例- Do not activate for project-level pipeline shape: \project-development.。缺失同样是 warningstrict 下失败。frontmatter 写法以模板为准name替换为技能名description替换为你技能的第三人称描述--- name: 新技能名 description: 第三人称描述说明该技能覆盖什么、何时使用含冒号必须整体加引号 ---为什么引号是硬性要求test_skill_frontmatter.py 中有一个回归测试明确守护description 中未加引号的冒号会被严格 YAML 解析器拒绝报invalid YAML这一缺陷且语料集成测试要求skills/下每个已发布技能的 description 都出现在带引号的行匹配\ndescription: 。模板与 CONTRIBUTING.md 对正文内容还有几条写作约束闸门虽不做全文语义检查但属于仓库公开的发布标准Core Concepts写改变行为的机制不写通用背景可跨语料复用的行为模式应记入 researcher/mechanisms/registry.jsonl 并从语料索引链接。Practical Guidance必须可被 agent 执行工作流、清单、决策表或具体运行规则。Integration说明路由与组合边界相关技能用纯文本列出而非跨目录链接。数值、基准或供应商性能声明必须引用 researcher/claims/index.jsonl 中的claim-*ID否则要弱化措辞并移入带日期的参考资料。内容保持平台无关不出现平台专有工具名、厂商锁定示例或单一 agent 产品特性。注册到清单、文档与语料索引新目录建好后有五个文件必须同步更新否则对应闸门会报清单/索引与skills/目录不一致。1..claude-plugin/marketplace.json在唯一的plugins[0].skills数组中追加字符串./skills/新技能名。校验规则来自validate_repo.py与 validate_platform_compat.pymarketplace 必须恰好包含一个捆绑插件且source为./每个路径以./开头、不含..、对应目录真实存在且清单解析出的技能集合必须与skills/目录完全相等——漏加或多写都会报manifest skills differ from skills directory。2..plugin/plugin.jsonCONTRIBUTING 的说明.plugin/plugin.json通常只需改 version 或 description因为 Open Plugins 宿主会自动发现./skills/下的技能目录。但注意validate_repo.py也会检查该文件的skills字段如果你此前在此显式列出了路径清单发现集合必须与skills/目录一致需要同步追加。3. 根目录三份文档README.md必须包含skills/新技能名/链接形式或反引号包裹的新技能名之一校验器做精确字符串匹配缺失报missing exact published skill mention。惯例是加进对应类别的技能表格和 Available skills 列表README 安装部分写有 This installs all 17 skills in a single plugin这句总技能数描述不被校验器强制但建议顺手改为新总数。根 SKILL.md必须包含精确内部路径skills/新技能名/SKILL.md缺失报missing exact internal skill path。CLAUDE.md校验器会用实际技能数拼出期望短语如当前 17 个技能对应 17 skillCLAUDE.md 中未提及当前总数会报 warning——--strict模式下 warning 直接失败所以要把技能总数更新为 N1。4.researcher/corpus/index.json在 researcher/corpus/index.json 的skills数组中追加一条字段格式与现有条目一致新技能名、激活场景按实际情况替换{ name: 新技能名, path: skills/新技能名/SKILL.md, activation_scenarios: [激活场景一, 激活场景二], mechanism_ids: [], claim_ids: [] }校验规则skills的name集合必须与skills/目录完全相等每条path必须真实存在引用的mechanism_ids/claim_ids必须已存在于对应 JSONL没有就留空数组。5. 激活回归测试用例向 researcher/fixtures/activation-cases.jsonl 追加至少一条字段与现有条目相同{case_id:activation-新技能名-basic,prompt:一个明确指向新技能的任务描述,expected_primary_skill:新技能名,acceptable_secondary_skills:[],rejected_skills:[边界易混淆的相邻技能],reason:为什么该 prompt 属于新技能}CONTRIBUTING 要求当边界容易混淆时在 rejected_skills 中放入被拒绝或相邻的技能。check_activation_cases.py 用 token 重叠对 prompt 与每个技能的 description When to Activate 文本排序通过条件是expected_primary_skill落在 top 3且rejected_skills中的技能都不在 top 3。如果你的新技能与某相邻技能反复抢激活就回到 description 和 Do not activate 边界上改措辞。可选分支新技能若沉淀了可复用的行为模式在 researcher/mechanisms/registry.jsonl 记录一条必填字段含mechanism_id、owning_skill、status、activation_scenario、behavior_change、evidence、failure_modes其中owning_skill必须指向已发布技能并把mechanism_id回填到 corpus index 的mechanism_ids若正文引用了数值声明则在 researcher/claims/index.jsonl 补claim-*记录。没有这些内容时留空即可通过校验。依次运行全部闸门在仓库根目录按 CONTRIBUTING.md 的顺序执行python3 -m unittest researcher.scripts.tests.test_skill_frontmatter python3 researcher/scripts/validate_platform_compat.py --require-reference-validator python3 researcher/scripts/validate_repo.py --strict python3 researcher/scripts/skill_health.py --strict --no-history python3 researcher/scripts/check_activation_cases.py python3 researcher/scripts/run_benchmarks.py各闸门检查内容与成功判据frontmatter 单元测试覆盖解析器各分支并含语料集成测试——skills/下每个已发布技能 frontmatter 零 issue 解析、name等于目录名、description 在带引号的行上模板与根SKILL.md同样要求严格 YAML 可解析。全部通过时 unittest 无失败计数、退出码 0。平台兼容闸门对每个技能做严格 YAML 解析、命名与 description 长度检查交叉核对.plugin/plugin.json与.claude-plugin/marketplace.json的发现集合模拟.cursor/skills、.claude/skills、.codex/skills、.agents/skills四种本地安装布局并对每个技能目录调用agentskills validate。--require-reference-validator表示 CLI 缺失时直接失败报错文本agentskills CLI not found; install with python -m pip install skills-ref。成功输出形如N 为技能总数Platform compatibility passed: N skills, 4 local install layouts仓库结构闸门--strict检查技能正文、两份清单、根目录文档、researcher 操作系统必需文件、rubric 关键阈值词、mechanism/claim 的引用完整性、corpus index 与激活用例字段。成功输出形如Validation passed: 0 errors, 0 warnings, N skills--strict把 warning 也计为失败退出码 1所以上面0 warnings必须真实成立。技能健康闸门--strict --no-history对每个技能计算确定性质量分必选章节、gotcha 数量、代码示例数、内部链接可达性、数值声明的 claim 覆盖率、激活用例数、机制数、frontmatter 有效性分数低于 0.75、超过 500 行、缺章节或 frontmatter 无效都会被标记--strict下有任何技能被标记即退出非零。新技能至少需要 1 条激活用例和 1 条已注册机制才能拿到满分档缺一项各扣对应权重。成功输出形如Skill health: corpus... min... flagged0 skillsN副作用说明该脚本默认把完整报告写入researcher/reports/skill-health.json--no-history表示不向历史文件追加记录。激活用例闸门按上文规则跑全部用例。成功输出形如Activation cases passed: N cases, 0 failures失败时逐条打印case_id、期望技能与实际 top 3可直接定位是哪个相邻技能抢了排序。基准总闸门run_benchmarks.py组合运行validate_repo.py --strict、check_activation_cases.py以及对researcher/benchmarks/scenarios/对抗场景的形状检查另两项必须同时通过。成功输出形如Benchmarks passed: 3 checks, 0 failures, X scenarios不带--record时不会写researcher/reports/benchmark-history.jsonl本地运行无历史副作用。失败信息对照闸门报错大多直接指出文件与原因常见消息与处理方式报错消息原因处理name X does not match directory Yfrontmattername与目录名不一致改name或目录名保持一致name must be lowercase kebab-case without repeated hyphens命名含大写、下划线或连续连字符按 kebab-case 重命名目录与namedescription exceeds 1024 charactersdescription 超长压缩到 1024 字符内SKILL.md exceeds 500 lines (N)正文超限详细资料移入references/并链接missing required section: ## X缺必选 H2 章节按模板补齐对应章节missing explicit non-activation boundarywarning没有 Do not activate 边界补边界段落指向相邻技能description may not be third personwarningdescription 出现 I can 等措辞改第三人称strict 下必须修manifest skills differ from skills directory: manifest[...] skills[...]marketplace 清单与skills/目录不一致对照两个列表补/删plugins[0].skills条目corpus skill index differs from skills directory: [...] ! [...]corpus index 未同步更新 researcher/corpus/index.jsonmissing exact published skill mention: XREADME 未提及新技能按上节补链接或反引号技能名missing exact internal skill path: X根 SKILL.md 缺内部路径补skills/X/SKILL.md字面路径does not mention current skill count phrase N skillwarningCLAUDE.md 技能总数未更新更新总数短语agentskills validate skills/X failed: msg上游参考校验器发现问题按消息中的具体信息修正完成判定与提交六条命令退出码全部为 0、输出如上各passed/0 failures信息即新技能跑通了仓库当前的全部确定性闸门。收尾注意两点均来自 CONTRIBUTING.md不要向 PR 引入新的已提交运行态researcher/runs/*/种子 run 除外、researcher/queue/*.jsonl及相关报告文件都在 gitignore 中bug 用例应放进researcher/fixtures/。闸门通过后可以提交 PR描述清楚变更内容按仓库约束merge 与 push 保留给人类操作。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考