Contributing to cosmosdb-agent-kit

Thank you for your interest in contributing! This project is a collection of skills for AI coding agents working with Azure Cosmos DB.

Ways to Contribute

1. Add New Rules (Most Common)

Add new best practice rules to the existing cosmosdb-best-practices skill:

1. Create a new rule file in skills/cosmosdb-best-practices/rules/
2. Follow the naming convention: {prefix}-{description}.md
   • Use an existing prefix that matches the category (e.g., query-, model-, sdk-)
3. Use the template at skills/cosmosdb-best-practices/rules/_template.md
4. Include valid frontmatter with title, impact, and tags
5. (Optional) Run npm run build to preview the compiled AGENTS.md locally. It is generated on demand and is not committed, so you do not need to include it in your PR.
6. Add an evaluation task (see Writing Tests below)

Example rule file name: query-use-top-clause.md

2. Improve Existing Rules

• Review and enhance rule content for clarity or accuracy
• Add missing examples or edge cases
• Update rules as Azure Cosmos DB evolves
• Fix typos or grammatical errors

3. Create a New Skill

The kit is designed to host multiple focused skills. Each skill is self-contained in its own directory. To create a new skill:

1. Create a new directory under skills/ (kebab-case name)
2. Add the required files:

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition (frontmatter + content)
    metadata.json         # Required: version, organization, abstract, references
    README.md             # Required: documentation for the skill
    rules/                # Required for rule-based skills
      _sections.md        # Section metadata (defines prefixes and ordering)
      _template.md        # Template for new rules in this skill
      {prefix}-{name}.md  # Individual rule files

3. Define sections in rules/_sections.md with frontmatter:

---
sections:
  - { prefix: 'sizing-', name: 'Data Sizing', number: 1, impact: 'CRITICAL' }
  - { prefix: 'ru-', name: 'RU Calculation', number: 2, impact: 'HIGH' }
---

4. Build and validate:

# Build just your skill
npm run build:skill {skill-name}

# Or build all skills
npm run build

# Validate
npm run validate:skill {skill-name}

5. Create a matching eval directory at evals/{skill-name}/ (see Writing Tests)

4. Report Issues / Suggest Improvements

• Open GitHub issues for bugs, inaccuracies, or missing best practices
• Suggest new rule categories or skill ideas
• Share feedback on rule effectiveness

5. Test Compatibility

• Test skills with different AI agents (Claude Code, GitHub Copilot, Gemini CLI, Cursor)
• Report compatibility issues or unexpected behavior

Getting Started

# Clone the repo
git clone https://github.com/AzureCosmosDB/cosmosdb-agent-kit.git
cd cosmosdb-agent-kit

# Install dependencies
npm install

# Make changes to rules, then build
npm run build

# Validate your changes
npm run validate

Writing Tests (Optional)

The repo includes a Vally eval framework under evals/. Eval tasks are not currently enforced in CI (the mock executor cannot validate response content), but you're encouraged to add them alongside new rules for future use.

Adding a task for a new rule

Create a YAML file in evals/cosmosdb-best-practices/tasks/:

id: your-rule-name
name: "Short descriptive name"
description: |
  What this test validates — should map to a specific rule or behavior.
inputs:
  prompt: "A realistic user prompt that should trigger your rule's guidance"
expected:
  outcomes:
    - type: task_completed

Running tests locally

# Install Vally by following the instructions at https://github.com/microsoft/vally

# Run all eval tasks (mock executor — no API key needed)
vally run evals/cosmosdb-best-practices/eval.yaml -v

# Run a single task by name
vally run evals/cosmosdb-best-practices/eval.yaml --task "Your Task Name"

# Check skill readiness
vally check skills/cosmosdb-best-practices

Rule File Format

Each rule file should follow this structure:

---
title: Short descriptive title
impact: Critical | High | Medium | Low
tags:
  - relevant-tag
  - another-tag
---

## Description

Explain what this rule addresses and why it matters.

## Recommendation

Clear, actionable guidance.

## Example

Show code or configuration examples when applicable.

## References

- Link to official documentation

Pull Request Guidelines

1. One rule per PR for new rules (makes review easier)
2. Run validation before submitting: npm run validate
3. Do not commit AGENTS.md — it is generated on demand (release CI and benchmarking)
4. Write clear commit messages describing the change
5. Link related issues in the PR description
6. (Optional) Add an eval task in evals/ for your rule

PR Merge Requirements

Your PR must pass these checks before merge:

• npm run validate passes
• One approving review from a code owner

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on the content, not the contributor

Questions?

Open an issue with the question label if you need help getting started.

License

By contributing, you agree that your contributions will be licensed under the MIT License.