# Contribution Workflow for Adding New Agents to the Agency Repository > Learn the agency-agents contribution workflow for adding new AI agents. Fork, create a Markdown file, test, and submit a pull request to contribute. - Repository: [Michael Sitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) - Tags: how-to-guide - Published: 2026-03-09 --- **To contribute a new AI agent to the msitarzewski/agency-agents repository, fork the project, create a Markdown file in the appropriate category directory following the template defined in [`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md), test the agent locally, and submit a pull request that passes the community review checklist.** The `msitarzewski/agency-agents` repository maintains a curated catalog of specialized AI agents designed for professional workflows. Understanding the contribution workflow for adding new agents ensures your specialist integrates seamlessly with the existing ecosystem and meets the project's documentation and quality standards. ## Prerequisites: Fork and Clone Before creating new agents, fork the repository to your GitHub account and clone it locally: ```bash # Clone your fork git clone https://github.com//agency-agents.git cd agency-agents ``` ## Step-by-Step Contribution Workflow for New Agents ### Select the Appropriate Category Directory Agents in this repository are organized into topical folders. Choose the correct location for your specialist: - `engineering/` – Software development and technical implementation - `design/` – UX, UI, and visual design specialists - `marketing/` – Content, growth, and campaign management - `product/` – Product management and strategy - `project-management/` – Coordination and planning specialists - `testing/` – QA and validation agents - `support/` – Customer success and technical support - `spatial-computing/` – AR/VR and 3D environment specialists - `specialized/` – Niche or industry-specific agents - `strategy/` – High-level business and technical strategy If your agent does not fit existing categories, you may propose a new folder in your pull request description. ### Create the Agent Markdown File In the selected folder, create a Markdown file named after the agent role (e.g., [`engineering/engineering-database-engineer.md`](https://github.com/msitarzewski/agency-agents/blob/main/engineering/engineering-database-engineer.md)). The file must follow the **Agent Design Guidelines** specified in [[`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md)](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md#agent-design-guidelines). Required frontmatter: ```yaml --- name: Agent Name description: Concise description of the agent's purpose color: "#HEXCODE" --- ``` Required sections include: - **Identity & Memory** – Role definition and personality traits - **Core Mission** – Primary objectives and responsibilities - **Critical Rules** – Non-negotiable constraints and guidelines - **Technical Deliverables** – Expected outputs and artifacts - **Workflow** – Step-by-step operational procedures - **Communication Style** – Tone and interaction patterns - **Learning** – Knowledge acquisition methods - **Success Metrics** – Measurable outcomes - **Advanced Capabilities** – Specialized skills or integrations ### Test Your Agent Locally Before submitting, validate that your agent functions correctly in a real scenario. According to the repository workflow, you should run the agent using Claude Code or any supported tool: ```bash # Copy your agent to the local agents directory for testing cp engineering/engineering-database-engineer.md ~/.claude/agents/ # Test command example (in Claude Code interface): # "Activate Database Engineer to design a PostgreSQL schema for an e-commerce catalog." ``` Verify that deliverables, workflow steps, and personality behave as intended. Fix any inconsistencies before proceeding. ### Submit Your Contribution via Pull Request Once testing is complete, submit your changes through the standard GitHub workflow: ```bash # Create a feature branch git checkout -b add- # Stage and commit your agent file git add /.md git commit -m "Add – " # Push to your fork git push origin add- ``` Open a Pull Request against the main repository with: - **Title:** `Add – ` - **Body:** Summary of the agent's purpose, gap it fills, and testing methodology - **Checklist:** Include all items from the PR template in [[`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md)](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md#pr-template) ### PR Review and Iteration Community members and maintainers will review your submission against the checklist in [`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md). Common review points include: - Adherence to the agent template structure - Clarity of success metrics - Completeness of technical deliverables - Grammar and formatting consistency Address feedback by committing changes to your branch. The PR will update automatically. ### Merge and Post-Merge Automation Once approved, a maintainer merges your PR into the main branch. The new agent immediately becomes part of the catalog and appears in the repository's README roster. Post-merge, the integration scripts [[`scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh)](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh) and [[`scripts/install.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/install.sh)](https://github.com/msitarzewski/agency-agents/blob/main/scripts/install.sh) automatically regenerate deployment files to include your agent in the installation pipeline. ## Summary - **Fork and clone** the `msitarzewski/agency-agents` repository to your local environment. - **Select the appropriate category directory** from the ten available folders (e.g., `engineering/`, `design/`, `marketing/`). - **Create a Markdown file** following the strict template in [`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md) with required frontmatter and nine content sections. - **Test locally** using Claude Code or supported tools before submitting. - **Submit a Pull Request** using the format `Add – ` and complete the checklist from [`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md). - **Post-merge**, automation scripts [`scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh) and [`scripts/install.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/install.sh) integrate your agent into the deployment pipeline. ## Frequently Asked Questions ### What categories can I contribute to? The repository organizes agents into ten top-level directories: `engineering/`, `design/`, `marketing/`, `product/`, `project-management/`, `testing/`, `support/`, `spatial-computing/`, `specialized/`, and `strategy/`. If your agent does not fit these categories, you may propose a new folder in your pull request description. ### Do I need to use a specific template for new agents? Yes. All agents must follow the **Agent Design Guidelines** defined in [[`CONTRIBUTING.md`](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md)](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md#agent-design-guidelines). This includes YAML frontmatter with `name`, `description`, and `color` fields, plus nine required sections covering identity, mission, rules, deliverables, workflow, communication, learning, metrics, and advanced capabilities. ### How do I test my agent before submitting? You should run your agent in a real scenario using Claude Code or any supported tool. Copy your Markdown file to the local agents directory (e.g., `~/.claude/agents/`) and invoke the agent with a specific task to verify that deliverables, workflow steps, and personality behave as intended. Fix any inconsistencies before opening your pull request. ### What happens after my pull request is merged? Once merged, your agent immediately appears in the repository's README roster and catalog. The integration scripts [[`scripts/convert.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh)](https://github.com/msitarzewski/agency-agents/blob/main/scripts/convert.sh) and [[`scripts/install.sh`](https://github.com/msitarzewski/agency-agents/blob/main/scripts/install.sh)](https://github.com/msitarzewski/agency-agents/blob/main/scripts/install.sh) automatically regenerate deployment files to include your agent in the installation pipeline. You may also share success stories in GitHub Discussions or add case studies to the README.