# AGENT 说明

本文档用于描述本项目的结构、SKILL 目录规范以及说明文件的编写标准。

## 1. 项目结构

本项目是一个 Skill 集合仓库，旨在通过 Trae 等 AI 编程工具调用，赋予 Agent 各种垂直领域的专业能力。

整体目录结构如下：

```
shared_skills/
├── 16 个 Anthropic 官方 Skill/   # 官方示例 Skill 集合
│   ├── algorithmic-art/
│   ├── brand-guidelines/
│   ├── docx/
│   ├── pdf/
│   ├── pptx/
│   ├── xlsx/
│   └── ... (其他官方 Skill)
│
├── C 哥相关 Skill/              # C 哥个人 IP 相关 Skill
│   ├── cgerike-maker/          # C 哥日课生成器
│   ├── media-copywriter/       # 自媒体文案生成
│   └── 说明.txt                # 该分类下的用户说明书
│
├── 教育相关 Skill/              # 教育领域专用 Skill
│   ├── math-exam-generator/    # 数学试卷生成
│   ├── music-theory-exam/      # 乐理试卷生成
│   └── 说明.txt                # 该分类下的用户说明书
│
├── 职场相关 Skill/              # 职场办公效率 Skill
│   ├── bid-document-analyzer/  # 招标文件分析
│   ├── invoking-llm/           # 通用 LLM 调用
│   ├── resume-screener/        # 简历筛选
│   ├── zhangsan-redhead-generator/ # 红头文件生成
│   └── 说明.txt                # 该分类下的用户说明书
│
└── 自动查找网上 Skill 的 Skill/  # 元 Skill
    ├── find-skills/            # 用于查找其他 Skill
    └── 说明.txt                # 该分类下的用户说明书
```

## 2. SKILL 目录结构规范

每个 Skill 必须包含在一个独立的文件夹中，且必须包含以下核心文件：

```
skill-name/                 # Skill 根目录
├── SKILL.md                # [核心] Skill 定义文件，包含 Prompt 和使用指南
├── LICENSE.txt             # 许可证文件
├── README.txt              # (可选) 简要说明
├── scripts/                # (可选) Python/Shell 脚本目录，用于执行复杂逻辑
│   ├── script_name.py
│   └── requirements.txt    # 依赖声明
├── references/             # (可选) 参考资料目录，存放知识库、模板、规则文件
│   ├── template.docx
│   ├── rules.md
│   └── knowledge.pdf
├── examples/               # (可选) 示例输入输出文件
│   ├── input_example.md
│   └── output_example.md
└── .config/                # (可选) 配置文件目录，用于存放 API Key 等敏感信息
    └── api_key.txt         # (通常被 .gitignore 忽略)
```

### 关键文件说明：

*   **SKILL.md**：这是 Agent 识别和使用 Skill 的入口。必须包含 `frontmatter`（元数据）和详细的操作步骤。
*   **scripts/**：当 Skill 需要执行复杂计算、文件处理或 API 调用时，应将逻辑封装在脚本中，由 SKILL.md 指导 Agent 调用。
*   **references/**：存放 Skill 运行所需的静态资源。**Agent 在执行任务时，应优先检查此目录下的文件，而不是要求用户每次都提供（如公司资质、筛选标准、红头文件模板等）。**

## 3. 说明文件编写结构 (说明.txt)

每个 Skill 分类目录下（如 `职场相关 Skill/`），都必须有一个 `说明.txt` 文件。这个文件是**面向最终用户（小白用户）**的使用指南。

**编写原则：**
1.  **大白话**：严禁使用技术术语（如 "CLI", "JSON", "XML"），除非必须提及。
2.  **场景化**：用"简单来说"告诉用户这个工具在什么场景下用。
3.  **步骤化**：用"怎么用"列出 1-2-3 步傻瓜式操作指南。
4.  **去黑盒**：用"背后的逻辑（给好奇宝宝）"简单解释原理，增加信任感。
5.  **纯文本**：使用 `.txt` 格式，避免 Markdown 渲染问题，保持最朴素的易读性。

**标准结构模板：**

```text
这是"[分类名称]"的中文通俗说明书。
旨在用最简单的大白话，告诉大家这些工具是干嘛的、怎么用。

================================================================
【1】skill-name-1（中文俗名）
================================================================

【简单来说】
（用一两句话解释它的核心价值和适用场景）

【怎么用】
1. （准备工作，如：把文件放入文件夹、填写配置文件）
2. （交互指令，如：告诉它"帮我..."）
3. （结果反馈，如：它会生成一个...文件）

【背后的逻辑】（给好奇宝宝）
（可选，用通俗的比喻解释技术原理）

----------------------------------------------------------------
【2】skill-name-2（中文俗名）
================================================================
...（重复上述结构）
```

## 4. 经验教训 (Lessons Learned)

在编写 Skill 和说明文档时，请务必遵守以下经验：

1.  **避免过时信息**：不要在文档中提及具体的模型版本号（如 GPT-4o, Claude 3.5），除非该 Skill 强依赖特定版本。应使用通用描述或提示用户以最新版本为准。
2.  **避免误导性定价**：严禁使用"免费"、"福利"、"便宜"等主观或易变动的描述。
3.  **预置上下文**：Skill 应当利用 `references/` 目录预置尽可能多的上下文信息（如公司资质、筛选规则、模板），**避免让用户在每次对话中重复提供这些固定信息**。
4.  **明确配置路径**：涉及 API Key 配置时，必须给出极其精确的文件路径（如 `.ai/skills/xxx/.config/key.txt`）和文件格式要求（如"只能有一行，无空格"）。
5.  **模板保护**：对于依赖模板的 Skill（如红头文件生成），必须在文档中强调模板文件的位置和"不可删除/修改"的属性。
6.  **纯文本格式**：说明书 `说明.txt` 必须是纯文本格式，不使用 Markdown 语法（如 `**加粗**`），而是使用符号（如 `【】`、`====`）来区分层级。
