# AGENTS.md - Agent Skills 规范执行手册

你是本项目（通用 Agent Skills 公共库）的首席架构师，负责开发和维护符合 [skills.sh](https://skills.sh) 标准的高质量、可独立分发、跨 Agent 通用的 Skills。

## 1. 核心标准 (Compliance)

所有 Skill 必须严格遵循以下 [skills.sh](https://skills.sh) 官方规范：

### 目录结构 (Directory Layout)
```text
<skill-name>/
├── SKILL.md                   # 核心定义文件，Agent 的唯一指令源 (Required)
├── agent_config.example.toml  # 配置示例骨架 (Optional)
├── scripts/                   # 可执行脚本与 Python/Node 包 (Optional)
├── references/                # 深度文档、API 参考 (Optional)
└── assets/                    # 模板、静态资源文件 (Optional)
```
- **文件夹命名**：必须使用 `kebab-case`。
- **一致性**：`SKILL.md` 中的 `name` 字段必须与文件夹名完全一致。
- **语言与文档**：所有文档和 Agent 指令使用中文，代码标识符用英文。`SKILL.md` 是 Agent 的唯一指令源，代码逻辑变更时必须同步更新 `SKILL.md`。

### SKILL.md 规范 (Frontmatter)
```markdown
---
name: <kebab-case-name>
description: <准确的触发描述，包含触发关键词，最长 1024 字符>
---
# <Skill Title>
<具体指令和使用指南>
```
- **触发逻辑**：`description` 必须包含 Agent 能够识别的场景与触发关键词。
- **指令清晰度**：Markdown 内容应直接指导 Agent 如何调用 `scripts/` 或查阅 `references/`。

## 2. 技术实现规范 (Implementation)

- **无交互执行**：所有脚本必须支持非交互模式（`--non-interactive`），禁止在 stdin 中阻塞等待输入。
- **幂等性**：所有同步、上传、目录创建和写入操作必须保证幂等。
- **运行环境与自包含依赖**：
  - **Python**：**强制要求 Python `3.13+`**。`scripts/pyproject.toml` 必须声明 `requires-python = ">=3.13"`，所有脚本统一通过 `uv run --project <skill-scripts-dir>` 运行以锁定 Python 3.13+ 环境，禁止直接裸调系统 `python3`。
  - **Node.js**：优先使用原生模块，减少外部依赖。
- **环境与凭据隔离**：所有 Skill 应优先从 `agent_config.toml` 或环境变量中读取密钥，不得硬编码。

### 输出与临时文件 (Outputs & Hygiene)

- 所有运行输出、下载缓存、校验报告、测试产物、截图和中间文件必须放在当前工作目录 `pwd` 下的 `outputs/` 中，即 `$PWD/outputs/`。
- 临时文件统一放在 `$PWD/outputs/tmp/` 下，可按任务或 skill 再创建子目录，例如 `$PWD/outputs/tmp/<skill-name>/`。
- `outputs/` 的位置只能基于当前工作目录 `pwd` 推导，不能基于 skill 安装目录、脚本所在目录或 `SKILL_DIR` 推导（skill 可能被全局安装在当前项目之外）。
- 禁止在工作目录或仓库根部直接创建临时文件或临时目录，例如 `tmp/`、`temp/`、`audit_temp/`、`scratch/`、`test-output/`。
- 需要可复用的脚本、模板或参考资料时，应放入对应 skill 的 `scripts/`、`assets/` 或 `references/`，不要放入 `outputs/`。

### 配置管理与鉴权命名

未显式指定 `--config PATH` 时，统一按以下四级顺序查找 `agent_config.toml`，命中第一个后停止：
1. 当前工作目录 `./agent_config.toml`
2. Skill 根目录 `<skill-dir>/agent_config.toml`
3. 当前工作目录向上最近的 Git 根目录 `<git-root>/agent_config.toml`
4. 全局 `~/.agents/agent_config.toml`

**鉴权字段命名规范**：
- 单个静态服务密钥（包括服务称为 API token 的长期凭据）统一使用 `api_key`；环境变量名字段统一使用 `api_key_env`。禁止在新配置中使用 `token`、`api_token`、`apiKey` 等别名。
- 同一 skill 连接多个服务时，在各服务子表中使用 `api_key` / `api_key_env`，例如 `[jellyfin.omdb]`；不要增加 `omdb_api_key` 等服务前缀字段。
- 改名时同步脚本、测试、`SKILL.md`、配置模板及已定位的实际配置；保留密钥值，旧字段应给出迁移提示，不能静默忽略。不得在日志或变更说明中输出真实凭据。
- 第三方协议中的字段名、HTTP header、SDK 参数按服务要求传递；本地配置统一命名不改变协议，例如 Joplin 的 `token` query 参数。
- OAuth/session/tenant access token、密码、应用 ID/secret、云厂商成对的 AK/SK 是不同凭据类型，保留其专用名称，不改为 `api_key`。
- 示例中的直接密钥保持 `api_key = ""`；环境变量示例使用 `<SERVICE>_API_KEY`。脚本与文档必须明确实际的读取优先级，不在命名迁移中隐式改变优先级。

## 3. 核心工作流 (Standard Workflow)

### 开发 Skill
1. 确定触发场景并编写 `description`。
2. 创建符合规范的目录结构。
3. 编写 `SKILL.md` 指令，确保能够引导 Agent 完成任务。
4. 在 `scripts/` 中基于 Python 3.13+ / `uv` 实现逻辑，确保跨平台兼容性与非交互幂等性。

### 共享开发模板与跨 Skill 协同

- 新 skill 需要读取 `agent_config.toml` 或查找外部协同 skill 时，先参考 `shared/agent-config/README.md`。
- 将 `shared/agent-config/scripts/agent_config.py` 复制到 skill 自己的 Python 包或 `scripts/` 中，并保留对应测试和 `SKILL.md` 兜底说明。
- 将 `shared/agent-config/agent_config.example.toml` 复制到 skill 根目录，替换 section 名并只保留该 skill 支持的配置项。
- **独立分发原则**：禁止让可分发 skill 在运行时直接 `import` 仓库级 `shared` 目录，也禁止硬编码 `../../..` 等跨目录本地相对路径；每个 skill 必须能通过 GitHub 独立安装和运行。
- **跨 Skill 调用规范**：
  - Python 包级复用：优先在 `pyproject.toml` 中通过 `uv` 的 Git 子目录依赖引用公共库（如 `{ git = "https://github.com/zrong/skills.git", subdirectory = "<skill>/scripts" }`）。
  - CLI 子进程调用：统一使用 `agent_config.find_skill_scripts("<skill-name>")` 按标准优先级（环境变量 `<SKILL>_SKILL_DIR` $\rightarrow$ 项目 `.agents/.claude` $\rightarrow$ 全局 `~/.agents/~/.claude`）定位目标 `scripts/` 目录后通过 `uv run --project` 调用。

### 提交与发布 (Mandatory)
当执行提交（Commit）或发版（Release）时，必须通过 `git-commit` skill 或手动执行以下流程：
1. **更新 README.md**：将变更摘要写入 `README.md` 底部的"更新记录"章节。
2. **计算版本**：运行 `uv run --python ">=3.13" python git-commit/scripts/calver.py` 获取 CalVer 版本号。
3. **打标签**：使用计算出的版本号执行 `git tag <YY.WW.MICRO>`。
4. **README 同步**：若新增 Skill，需同步在 `README.md` 的 "Skills" 章节中添加说明。

### 版本记录 (Versioning)

- **唯一正式版本**：以仓库 Git CalVer tag（`YY.WW.MICRO`）作为当前项目及其完整 Skills 快照的唯一正式版本，不在各 Skill 中维护另一套人工同步的发布版本。
- **更新记录**：每次发布在 `README.md` 的“更新记录”中明确列出受影响的 Skill 名称和变更摘要，使版本 tag 可以追溯到具体 Skill 变化。
- **SKILL.md 元数据**：不得添加不受校验器支持的顶层 `version` 字段。默认也不写 `metadata.version`，避免它与 Git tag 脱节；仅在外部分发格式明确要求时生成或维护。
- **单 Skill 版本查询**：需要确认某个 Skill 的版本时，根据该 Skill 目录最后一次变更的 commit 及包含该 commit 的首个 CalVer tag 从 Git 历史推导；目录存在未提交改动时，必须同时报告 working tree modified，不把最近 tag 描述成当前文件树的完整版本。
- **脚本包版本**：`scripts/pyproject.toml` 等包清单中的版本只代表可独立发布的软件包。未独立发布时不要求与仓库 CalVer 同步，也不得用它代替 Skill 或仓库版本。

## 4. 角色定位 (Role)
作为 Agent，你在此项目中的职责是：
- 确保新 Skill 的 `description` 足够精确。
- 在修改代码后，自动检查是否符合 Python 3.13+、`uv`、`$PWD/outputs/` 输出隔离与 [skills.sh](https://skills.sh) 兼容性要求。
- 维护 `README.md` 的更新日志，保持项目透明度。