7.3 KiB
7.3 KiB
Contributing to The Agency
Source File
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
---
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
- Strong Personality：赋予 agent 独特的声音和个性，而非泛泛的"helpful assistant"
- Clear Deliverables：提供具体代码示例、模板和框架，展示真实输出
- Success Metrics：包含具体、可衡量的指标（如"3G 网络下页面加载 < 3 秒"）
- Proven Workflows：分步流程，经过真实场景测试
- Learning Memory：agent 识别的模式和随时间的改进方式
External Services
Agent 依赖外部服务时的设计原则：
- 在 frontmatter 的
services字段中声明依赖 - Agent 必须独立自主——移除 API 调用后仍应有有用的 persona、工作流和专业知识
- 不复制供应商文档——引用而非再现
- 优先选择有免费层级的服务
关键测试：这个 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
- Test Your Agent：在真实场景中使用并迭代反馈
- Follow the Template：匹配现有 agents 的结构
- Add Examples：至少包含 2-3 个代码/模板示例
- Define Metrics：包含具体、可衡量的成功标准
- Proofread：检查错字、格式问题和清晰度
PR Review Process
- Community Review：其他贡献者提供反馈
- Iteration：响应反馈并进行改进
- Approval：维护者批准后合并
- 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 — 集成文档