# Contributing to The Agency

## Source File
- [[raw/Agent/agency-agents/CONTRIBUTING.md]]

## Overview

The Agency 是一个开源 AI Agent 精选集合，其 CONTRIBUTING.md 定义了完整的贡献指南体系，涵盖行为准则、贡献方式、Agent 设计规范、PR 流程和写作风格指南。

## Code of Conduct

项目遵守明确的行为准则：
- **Be Respectful**：尊重每个人，鼓励健康辩论，拒绝人身攻击
- **Be Inclusive**：欢迎并支持各种背景和身份的人
- **Be Collaborative**：协作创造优于独自创作
- **Be Professional**：保持讨论聚焦于改进 agents 和社区

## How to Contribute

### 1. 创建新 Agent

贡献者在选择合适分类后，按模板创建 Agent 文件：
- `engineering/` — 软件开发专家
- `design/` — UX/UI 和创意专家
- `finance/` — 财务规划和投资专家
- `game-development/` — 游戏设计与开发专家
- `marketing/` — 增长和营销专家
- `paid-media/` — 付费获客专家
- `product/` — 产品管理专家
- `project-management/` — PM 和协调专家
- `testing/` — QA 和测试专家
- `support/` — 运营和支持专家
- `spatial-computing/` — AR/VR/XR 专家
- `specialized/` — 不属于以上分类的专家

### 2. 改进现有 Agent

贡献方向包括：
- 添加真实案例和使用场景
- 用现代模式增强代码示例
- 基于最新最佳实践更新工作流
- 添加成功指标和基准
- 修复错字、改善清晰度、增强文档

### 3. 分享成功案例

通过 GitHub Discussions、案例研究、博客文章和视频教程分享。

### 4. 报告问题

提供清晰的复现步骤、使用场景上下文和建议的解决方案。

## Agent Design Guidelines

### Agent 文件结构

Agent 文件遵循 YAML frontmatter + Markdown 内容的两段式结构：

#### YAML Frontmatter
```yaml
---
name: Agent Name
description: One-line description
color: colorname or "#hexcode"
emoji: 🎯
vibe: One-line personality hook
services:          # optional — only if the agent requires external services
  - name: Service Name
    url: https://service-url.com
    tier: free    # free, freemium, or paid
---
```

#### Content Sections

文档定义了 Agent 文件的两大语义分组：

**Persona（Agent 的身份）**：
- Identity & Memory — 角色、个性、背景
- Communication Style — 语气、声音、方式
- Critical Rules — 边界和约束

**Operations（Agent 的行为）**：
- Core Mission — 主要职责
- Technical Deliverables — 具体输出和模板
- Workflow Process — 分步方法论
- Success Metrics — 可衡量成果
- Advanced Capabilities — 专业化技术

#### 结构原则

不需要特殊格式——只需将 persona 相关部分（身份、沟通、规则）与操作部分（使命、交付物、工作流、指标）分开。`convert.sh` 脚本使用这些章节标题自动将 agents 拆分为工具特定格式。

### Agent Design Principles

1. **Strong Personality**：赋予 agent 独特的声音和个性，而非泛泛的"helpful assistant"
2. **Clear Deliverables**：提供具体代码示例、模板和框架，展示真实输出
3. **Success Metrics**：包含具体、可衡量的指标（如"3G 网络下页面加载 < 3 秒"）
4. **Proven Workflows**：分步流程，经过真实场景测试
5. **Learning Memory**：agent 识别的模式和随时间的改进方式

### External Services

Agent 依赖外部服务时的设计原则：
1. 在 frontmatter 的 `services` 字段中声明依赖
2. Agent 必须独立自主——移除 API 调用后仍应有有用的 persona、工作流和专业知识
3. 不复制供应商文档——引用而非再现
4. 优先选择有免费层级的服务

关键测试：*这个 agent 是为用户服务的，还是为供应商服务的？*

### Qwen Code Compatibility

Agent body 支持 `${variable}` 模板语法以实现动态上下文（如 `${project_name}`、`${task_description}`）。Qwen SubAgents 使用最小化 frontmatter：仅需要 `name` 和 `description`；`color`、`emoji` 和 `version` 字段被省略。

### What Makes a Great Agent

**Great agents have**：
- ✅ 狭窄而深入的专业化
- ✅ 独特的个性和声音
- ✅ 具体的代码/模板示例
- ✅ 可衡量的成功指标
- ✅ 分步工作流
- ✅ 真实场景测试和迭代

**Avoid**：
- ❌ 泛化的"helpful assistant"个性
- ❌ 模糊的"我将帮助你..."描述
- ❌ 无代码示例或交付物
- ❌ 过于宽泛的范围（什么都做等于什么都没做）
- ❌ 未经测试的理论方法

## Pull Request Process

### PR 边界管理

最佳路径是一个 markdown 文件（一个新或改进的 agent），这是最理想的情况。

**始终欢迎作为 PR**：
- 添加新 agent（一个 `.md` 文件）
- 改进现有 agent 的内容、示例或个性
- 修复错字或澄清文档

**先开 Discussion**：
- 新工具、构建系统或 CI 工作流
- 架构变更（新目录、新脚本、网站生成器）
- 跨多文件变更
- 新集成格式或平台

**始终关闭的内容**：
- 已提交构建输出（`_site/`、编译资产、转换后的 agent 文件）
- 批量修改现有 agents 而未先讨论的 PR

### Before Submitting

1. **Test Your Agent**：在真实场景中使用并迭代反馈
2. **Follow the Template**：匹配现有 agents 的结构
3. **Add Examples**：至少包含 2-3 个代码/模板示例
4. **Define Metrics**：包含具体、可衡量的成功标准
5. **Proofread**：检查错字、格式问题和清晰度

### PR Review Process

1. **Community Review**：其他贡献者提供反馈
2. **Iteration**：响应反馈并进行改进
3. **Approval**：维护者批准后合并
4. **Merge**：贡献成为 The Agency 的一部分

## Style Guide

### Writing Style

- **Be specific**："Reduce page load by 60%" 而非 "Make it faster"
- **Be concrete**："Create React components with TypeScript" 而非 "Build UIs"
- **Be memorable**：赋予 agents 个性，而非泛化的企业用语
- **Be practical**：包含真实代码，而非伪代码

### Formatting

- 一致使用 **Markdown formatting**
- 章节标题使用 **emojis**（便于扫描）
- 所有代码示例使用 **code blocks** 并标注语法高亮
- 使用 **tables** 对比选项或展示指标
- 使用 **bold** 强调，`code` 标注技术术语

### Tone

- **Professional but approachable**：不过于正式或随意
- **Confident but not arrogant**："Here's the best approach" 而非"Maybe you could try..."
- **Helpful but not hand-holding**：假设能力，提供深度
- **Personality-driven**：每个 agent 应有独特声音

## Recognition

重要贡献者将被：
- 列在 README 致谢部分
- 在发布说明中突出
- 在"本周最佳 Agent"展示中亮相（如适用）
- 在 agent 文件本身中获得荣誉

## Questions & Resources

- **General Questions**: GitHub Discussions
- **Bug Reports**: GitHub Issues
- **Feature Requests**: GitHub Issues
- **Community Chat**: Join discussions

### For New Contributors

- README.md — 总览和 agent 目录
- engineering-frontend-developer.md — 结构良好的 agent 示例
- marketing-reddit-community-builder.md — 个性出色的示例
- design-whimsy-injector.md — 创意专家示例

## Related

- [[The Agency]] — 项目主实体
- [[agency-agents]] — GitHub 仓库实体
- [[agency-agents-examples]] — Examples 页面
- [[agency-agents-integrations]] — 集成文档