ManySkills/AGENTS.md

ManySkills Agent Guide

Project Overview

本仓库集中维护 5 个 Codex 插件及其 skill 源码。日常按插件逐个更新，发布时将所有插件作为一个整体发版。统一版本以根目录 VERSION 为准，当前统一版本为 1.2.0。

Scope

• 本文件适用于整个仓库；子目录中的 AGENTS.md 可为其作用域提供更具体的规则。
• 当前任务中的用户指令优先于仓库指南。
• 外部命令必须加 rtk 前缀；需要完整原始输出时使用 rtk proxy。PowerShell cmdlet 和控制流不加此前缀。

Key Paths

• VERSION：整个仓库的统一发布版本。
• README.md：插件清单、版本约定与更新发版流程。
• plugins/generate-agents-md/：AGENTS.md 生成器。
• plugins/design-md/：DESIGN.md 生成器。
• plugins/eapil-gpt2-image/：图像生成与编辑。
• plugins/eapil-llmapi-structured/：LLM 通用调用指南，含结构化输出、检索和 Decisions。
• plugins/eapil-voice/：音频服务指南，含语音、转录、降噪、音乐、音效和歌曲。
• 每个插件包的 .codex-plugin/plugin.json 定义名称、版本、入口和市场信息；skills 目录包含说明、脚本及配套资源。

Versioning

• 5 个插件的 manifest version 必须与 VERSION 完全一致；新加入的插件也沿用统一版本。
• 已导入插件统一从 1.0.0 开始，原市场版本只作为来源历史，不作为本仓库版本基准。
• 日常逐个更新插件时，不单独提升某个插件版本。实际发版时一次更新 VERSION 和所有插件的 manifest version，包括本次未修改功能的插件。
• 整体版本遵循语义化版本号：修复升 patch，兼容的新功能升 minor，不兼容变更升 major；多个变更取所需最高级别。
• 整体发布 tag 使用 v 加统一版本号，例如 v1.0.1；不使用插件独立版本 tag。
• 每次发布说明列出本次有变化的插件、变更内容、兼容性和验证结果。

Working Rules

• 修改前先读目标插件的 SKILL.md，按任务需要读取其 references、脚本或模板。
• 在本仓库修改源码；不要将本机插件缓存当作维护源或用缓存覆盖仓库修改。
• 保持插件包可独立使用，维护 manifest 中的相对路径与配套资源。
• 保留作者、许可证、来源声明和市场链接；需要更改时依据当前任务处理。
• 逐个完成用户要求的插件更新，保持改动范围清晰；提交只暂存明确的任务路径。
• 修改说明、参数或接口时同步相关示例；行为变化只运行与改动相关的验证。
• Git 推送和 tag 不会自动发布到原市场；市场同步单独按明确的发布目标执行。

Skill Maintenance

• 更新 skill 时仅保留能改变决策的知识：准确触发、非显然约束、按需资料和可验证结果。
• 按任务范围读取资料；固定流程只用于偏离会导致具体错误的操作，避免无依据的审批和通用说教。
• 实质性重写参照 skill 更新准则，以行为验证改进，不用固定章节或字数替代质量。

Quick Commands

在仓库根目录执行：

rtk git status --short --branch
rtk rg --files --hidden -g '!.git/**' plugins
rtk proxy python plugins/generate-agents-md/skills/generate-agents-md/scripts/validate_agents_md.py --repo . --file AGENTS.md

需要检查完整差异时使用 rtk proxy git diff；提交前使用 rtk git diff --cached --check 检查已暂存内容。

Definition of Done

• 用户要求的目标插件已更新，相关说明和示例一致。
• 所有插件 manifest JSON 可解析，名称正确，声明的 skill 入口和图标路径存在。
• 所有插件版本与 VERSION 一致；发版时 README 的版本记录同步更新。
• 修改 AGENTS.md 后运行上方的指南校验；脚本行为变化运行对应验证，并报告不能运行的检查及原因。
• 交付时说明修改范围、验证结果，以及是否已提交、推送或发布。

Boundaries

• 永不将真实 API Key、PAT、凭据、运行日志或生成内容提交到仓库。
• 保留用户已有修改，不通过强推、清理或重置覆盖工作。
• 仅按当前任务授权执行提交、推送、创建 tag 或市场发布；用户要求配置或本地修改时，不自动推导为已授权发布。