# ManySkills Agent Guide

## Project Overview

本仓库集中维护 5 个 Codex 插件及其 skill 源码。日常按插件逐个更新，发布时将所有插件作为一个整体发版。统一版本以根目录 `VERSION` 为准，当前统一版本为 1.1.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 更新准则](docs/skill-maintenance.md)，以行为验证改进，不用固定章节或字数替代质量。

## Quick Commands

在仓库根目录执行：

```powershell
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 或市场发布；用户要求配置或本地修改时，不自动推导为已授权发布。