AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

Repository Overview

A collection of skills for AI coding agents working with Azure Cosmos DB. Skills are packaged instructions and scripts that extend agent capabilities.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    AGENTS.md             # Required: compiled rules (generated)
    metadata.json         # Required: version and metadata
    README.md             # Required: documentation
    rules/                # Required for rule-based skills
      _sections.md        # Section metadata
      _template.md        # Template for new rules
      {prefix}-{name}.md  # Individual rule files

Naming Conventions

• Skill directory: kebab-case (e.g., cosmosdb-best-practices)
• SKILL.md: Always uppercase, always this exact filename
• AGENTS.md: Always uppercase, always this exact filename
• Rule files: prefix-description.md (e.g., model-embed-related.md)

SKILL.md Format

---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases.}
license: MIT
metadata:
  author: cosmosdb-agent-kit
  version: "1.0.0"
---

# {Skill Title}

{Brief description of what the skill does.}

## When to Apply

{List of scenarios when this skill should be used}

## Rule Categories by Priority

{Table showing categories and their impact levels}

## Quick Reference

{Organized list of all rules by category}

Best Practices for Context Efficiency

Skills are loaded on-demand — only the skill name and description are loaded at startup. The full SKILL.md loads into context only when the agent decides the skill is relevant. To minimize context usage:

• Keep SKILL.md under 500 lines — put detailed reference material in AGENTS.md
• Write specific descriptions — helps the agent know exactly when to activate the skill
• Use progressive disclosure — reference supporting files that get read only when needed

Output

The build process compiles individual rule files into AGENTS.md:

npm run build
# or
node scripts/compile.js

Troubleshooting

Build Issues

• Ensure all rule files have valid frontmatter (title, impact, tags)
• Check that rule files use the correct prefix for their section
• Verify metadata.json exists and has valid JSON

Creating the Zip Package

After creating or updating a skill:

cd skills
zip -r cosmosdb-best-practices.zip cosmosdb-best-practices/

End-User Installation

Document these installation methods for users:

Claude Code:

cp -r skills/cosmosdb-best-practices ~/.claude/skills/

GitHub Copilot / VS Code:

cp -r skills/cosmosdb-best-practices ~/.copilot/skills/

Using add-skill:

npx skills add AzureCosmosDB/cosmosdb-agent-kit