Skip to content

Contributing Guidelines

Thank you for your interest in contributing to Seer Marketing Agents! This guide will help you get started with our development workflow and standards.

Getting Started

To begin contributing, follow these steps to set up your local development environment:

  1. Fork and Clone: Fork the repository on GitHub and clone it to your local machine. 
    git clone https://github.com/your-username/agents-infra.git
cd agents-infra
  2. Install Dependencies: Install the necessary tools and dependencies. 
    npm install -g opencode-ai
# If working on Python scripts
pip install -r requirements.txt
  3. Environment Setup: Copy the example environment file and add your API keys. 
    cp .env.example .env
  4. Verify Setup: Run the tests to ensure everything is working correctly. 
    pytest tests/

Code Style & Conventions

Maintaining a consistent codebase is crucial for our modular architecture.

  • File Naming: Use kebab-case for all filenames (e.g., content-audit.md, seo-methods.md).
  • Directory Structure: Always include a README.md in new directories to explain their purpose.
  • Documentation: Every new agent, skill, or command must be documented in its respective directory and added to the Agent Catalog.
  • DRY Principle: Shared standards (tone, quality, prompt patterns) live in core-dependencies. Do not duplicate them in division plugins.

Testing Requirements

We maintain high standards for code quality and reliability. All contributions must include appropriate tests.

  • Unit Tests: Required for all scoring algorithms and data processing logic. We aim for 95%+ coverage.
  • Integration Tests: Required for any new MCP server integrations to validate connection handling and error states.
  • End-to-End (E2E) Tests: Required for major workflows to ensure the agent can complete the full deliverable cycle.

To run tests: 

pytest tests/unit/           # Scoring algorithms
pytest tests/integration/    # MCP connections
pytest tests/e2e/            # Full workflows

Pull Request Process

  1. Create a Feature Branch: Use a descriptive name for your branch. 
    git checkout -b feature/your-feature-description
  2. Implement Changes: Follow the patterns established in existing plugins (e.g., the SEO plugin).
  3. Write/Update Tests: Ensure your changes are covered by tests and that all existing tests pass.
  4. Update Documentation: Update the Wiki and any relevant README files.
  5. Submit PR: Create a pull request with a clear description of the changes, the problem they solve, and how they were tested.

Commit Conventions

We use semantic commit messages to keep our history readable and searchable.

feat(seo): add keyword gap analysis workflow
fix(mcp): handle BigQuery timeout gracefully
docs: update plugin architecture guide
test: add e2e test for content audit workflow
refactor(analytics): migrate to plugin system
chore: update dependencies

What to Contribute

We welcome a wide range of contributions, including:

  • New Commands: Workflows for SEO, Analytics, Paid Media, or Operations.
  • Methodology Skills: New domain-specific skills and resources.
  • MCP Integrations: Connectors for new data sources and marketing tools.
  • Bug Fixes: Improving stability and handling edge cases.
  • Documentation: Clarifying guides and adding examples.

Security & Privacy

CRITICAL

Security is our top priority. Never commit sensitive information to the repository.

  • No Credentials: Never commit API keys, passwords, or personal access tokens.
  • Use Environment Variables: Use .env files for local development and ensure they are gitignored.
  • Sanitize Data: When providing examples or test fixtures, ensure all client data is thoroughly sanitized or replaced with placeholder data.
  • Follow Least Privilege: MCP servers should only have the permissions necessary to perform their tasks.

Capabilities Index

The Capabilities Index is auto-generated from the repository. When adding new skills, commands, or agents, the index should be updated.

Manual Update

Run the generator script: 

python3 scripts/generate-capabilities-index.py

Optional: Pre-Commit Hook

To auto-update the index on every commit, install the pre-commit hook:

cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# Auto-update capabilities index when skills/commands/agents change

CHANGED_FILES=$(git diff --cached --name-only)

if echo "$CHANGED_FILES" | grep -qE "(SKILL\.md|commands/.*\.md|agents/.*\.md)"; then
    echo "Detected skill/command/agent changes, updating capabilities index..."
    python3 scripts/generate-capabilities-index.py
    git add docs/wiki/practitioners/capabilities-index.md
fi
EOF
chmod +x .git/hooks/pre-commit

Note

The .git/hooks/ directory is not versioned by Git. Each developer must install the hook locally.