AGENTS.md · ClickHouse/agent-skills

Sections

1. Repository Overview
2. Repository Structure
3. Creating a New Skill
4. Contributing Guidelines
5. Impact Levels

First lines (shown under the repo's Apache-2.0 license)

# 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 agents working with ClickHouse databases and chdb (in-process ClickHouse for Python). Skills are packaged instructions and guidelines that extend agent capabilities for database design, query optimization, operational best practices, and in-process data analytics.

## Repository Structure

```
agent-skills/
├── skills/
│   ├── clickhouse-best-practices/   # ClickHouse optimization guidelines
│   │   ├── SKILL.md                 # Skill definition (overview)
│   │   ├── AGENTS.md                # Full compiled guide (generated)
│   │   ├── metadata.json            # Version, organization, abstract
│   │   ├── README.md                # Maintainer guide
│   │   └── rules/                   # Individual rule files
│   │       ├── _sections.md         # Section metadata
│   │       ├── _template.md         # Template for new rules
│   │       └── *.md                 # Rule files (e.g., query-use-prewhere.md)
│   ├── chdb-datastore/              # chdb pandas-compatible DataStore API
│   │   ├── SKILL.md                 # Skill definition and quick-start
│   │   ├── metadata.json            # Version, organization, abstract
│   │   ├── README.md                # Maintainer guide
│   │   ├── references/              # API reference docs
│   │   │   ├── api-reference.md     # DataStore method signatures
│   │   │   └── connectors.md        # All data source connection methods
│   │   ├── examples/
│   │   │   └── examples.md          # Runnable examples
│   │   └── scripts/
│   │       └── verify_install.py    # Environment verification
│   └── chdb-sql/                    # chdb SQL API
│       ├── SKILL.md                 # Skill definition and quick-start
│       ├── metadata.json            # Version, organization, abstract
│       ├── README.md                # Maintainer guide
│       ├── references/              # SQL reference docs
│       │   ├── api-reference.md     # query/Session/connect signatures
│       │   ├── table-functions.md   # ClickHouse table functions
│       │   └── sql-functions.md     # Commonly used SQL functions
│       ├── examples/
│       │   └── examples.md          # Runnable examples
│       └── scripts/
│           └── verify_install.py    # Environment verification
├── packages/
│   └── clickhouse-best-practices-build/  # Build tooling
│       ├── package.json             # Bun scripts
│       ├── tsconfig.json            # TypeScript config
│       └── src/
│           ├── config.ts            # Path configuration
│           ├── types.ts             # Type definitions
│           ├── parser.ts            # Markdown parser
│           ├── build.ts             # Build script
│           ├── validate.ts          # Rule validator
│           ├── validate-sql.ts      # SQL syntax validator
│           └── check-links.ts       # Internal link checker
└── .github/
    └── workflows/
        └── clickhouse-best-practices-ci.yml  # CI workflow
```

## Creating a New Skill

### Directory Structure

```
skills/
  {skill-name}/           # kebab-case directory name
    SKILL.md              # Required: skill definition
    AGENTS.md             # Generated: full compiled guide
    metadata.json         # Required: version, organization, abstract
    README.md             # Required: maintainer guide
    rules/                # Required: rule files
      _sections.md        # Section metadata
      _template.md        # Template for new rules
      *.md                # Individual rules
```

### Naming Conventions

- **Skill directory**: `kebab-case` (e.g., `clickhouse-best-practices`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Rule files**: `{section-prefix}-{descriptive-name}.md` (e.g., `query-use-prewhere.md`)
- **Section prefixes**: Match the section IDs defined in `_sections.md`

### SKILL.md Format

```markdown
---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases.}
license: MIT
metadata:
  author: {organization}
  version: "{version}"
---

# {Skill Title}

{Brief description of what the skill does.}

## When to Apply

Reference these guidelines when:
- {Use case 1}
- {Use case 2}

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | {Category} | {Impact} | `{prefix}-` |

## Quick Reference

{Brief overview of each category and key rules}

## How to Use

{Instructions on reading individual rule files}

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`
```

### Rule File Format

Use the template in `rules/_template.md`. Each rule file must have:

1. **YAML frontmatter**:
   ```yaml
   ---
   title: Rule Title
   impact: CRITICAL | HIGH | MEDIUM-HIGH | MEDIUM | LOW-MEDIUM | LOW
   impactDescription: Optional (e.g., "10-100× query speedup")
   tags: skill, category, specific-tags
   ---
   ```

2. **Rule structure**:
   - Brief explanation of why it matters
   - **Incorrect:** code example showing the anti-pattern
   - **Correct:** code example showing the best practice
   - Additional context, trade-offs, or when to apply
   - Reference links (optional)

### 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 separate files
- **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
- **Individual rule files** — allows agents to read only relevant rules on-demand
- **File references work one level deep** — link directly from SKILL.md to supporting files

### Build System Requirements