Contribution Workflow for Adding New Agents to the Agency Repository

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, 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:

# Clone your fork

git clone https://github.com/<your-username>/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). The file must follow the Agent Design Guidelines specified in [CONTRIBUTING.md](https://github.com/msitarzewski/agency-agents/blob/main/CONTRIBUTING.md#agent-design-guidelines).

Required frontmatter:

---
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:

# 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:

# Create a feature branch

git checkout -b add-<agent-name>

# Stage and commit your agent file

git add <category>/<agent-file-name>.md
git commit -m "Add <Agent Name> – <Category>"

# Push to your fork

git push origin add-<agent-name>

Open a Pull Request against the main repository with:

• Title: Add <Agent Name> – <Category>
• 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#pr-template)

PR Review and Iteration

Community members and maintainers will review your submission against the checklist in 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) and [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 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 <Agent Name> – <Category> and complete the checklist from CONTRIBUTING.md.
• Post-merge, automation scripts scripts/convert.sh and 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#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) and [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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}