# Naming Conventions

Consistent naming patterns for all claude-mods components.

## General Principles

1. **kebab-case** for all file and directory names
2. **Lowercase** always (no PascalCase, camelCase, or UPPERCASE)
3. **Descriptive** but concise
4. **No abbreviations** unless universally understood (API, CLI, SQL)

## Component Patterns

### Agents (`/agents`)

```
{domain}-expert.md
```

| Pattern | Example | Notes |
|---------|---------|-------|
| Tool | `firecrawl-expert.md` | Specific tools |
| Role | `project-organizer.md` | Activity/role-focused |

> The `{domain}-expert` suffix is the convention for domain-expert agents
> (e.g. `firecrawl-expert.md`). Worker agents like `git-agent` are the
> exception — they take a `-agent` suffix, signalling a background
> orchestrated worker rather than a `-expert` domain reference.

**Frontmatter:**

```yaml
---
name: firecrawl-expert       # Match filename (without .md)
description: <one line>      # Concise capability summary
model: sonnet|opus|haiku     # Recommended model
---
```

### Skills (`/skills`)

All skills follow the official Anthropic pattern with bundled resources:

```
{skill-name}/
├── SKILL.md              # Core workflow
├── scripts/              # Executable code (optional)
├── references/           # Documentation (optional)
└── assets/               # Output files (optional)
```

| Pattern | Example | Notes |
|---------|---------|-------|
| Operational expertise | `postgres-ops/` | Comprehensive domain knowledge (preferred) |
| Domain-specific | `python-async-ops/` | Domain + "-ops" |
| Tool knowledge | `sqlite-ops/` | Tool + "-ops" |
| Workflow | `git-ops/` | Activity-focused |
| Framework | `tailwind-ops/` | Framework + "-ops" |

**Naming guidance:** Use `-ops` for all skills providing domain knowledge. The `-ops` suffix signals comprehensive operational expertise - design, implementation, and operations.

**Frontmatter:**

```yaml
---
name: python-async-ops  # Match directory name
description: "<trigger phrases>"
compatibility: "<version requirements>"
allowed-tools: "<tool list>"
depends-on: [<skill-names>]
related-skills: [<skill-names>]
---
```

**Directory Structure:**
- All skills MUST include `scripts/`, `references/`, and `assets/` directories
- Directories may be empty if not currently used
- Ensures consistency and future extensibility

### Commands (`/commands`)

```
{action}.md
```

| Pattern | Example | Notes |
|---------|---------|-------|
| Single verb | `review.md` | Preferred |
| Compound | `testgen.md` | Concatenate, no hyphens |
| Conceptual | `atomise.md` | Abstract operations |

**Frontmatter:**

```yaml
---
description: "<one line summary with trigger phrases>"
---
```

### Rules (`/rules`)

```
{topic}.md
```

| Pattern | Example | Notes |
|---------|---------|-------|
| Tool guidance | `cli-tools.md` | Tool + purpose |
| Workflow | `commit-style.md` | Activity + aspect |
| Philosophy | `thinking.md` | Conceptual guidance |

**No frontmatter required** - plain markdown injected into context.

### Output Styles (`/output-styles`)

```
{personality}.md
```

| Pattern | Example | Notes |
|---------|---------|-------|
| Character | `vesper.md` | Named personality |
| Descriptor | `spartan.md` | Style type |
| Role | `mentor.md` | Persona type |

**Frontmatter:**

```yaml
---
keep-coding-instructions: true|false
---
```

### Hooks (`/hooks`)

```
{trigger}-{action}.sh
```

| Pattern | Example | Notes |
|---------|---------|-------|
| Pre-action | `pre-commit-lint.sh` | Before operation |
| Post-action | `post-edit-format.sh` | After operation |
| Warning | `dangerous-cmd-warn.sh` | Guardrails |

## Variable Naming

### Shell Scripts

```bash
# Constants: UPPER_SNAKE_CASE
readonly PROJECT_ROOT="/path/to/root"
readonly MAX_RETRIES=3

# Variables: lower_snake_case
local file_count=0
local current_branch=""

# Functions: lower_snake_case (verbs)
check_prerequisites() { ... }
run_tests() { ... }
```

### YAML Frontmatter

```yaml
# Keys: kebab-case
name: skill-name
depends-on: [other-skill]
allowed-tools: "Read Write"

# NOT these:
dependsOn: [bad]      # camelCase wrong
depends_on: [bad]     # snake_case wrong
```

### Markdown

- Headers: Title Case (`## Decision Frameworks`)
- Tables: Title Case headers, sentence case content
- Code blocks: Language-appropriate conventions

## Anti-patterns

```
BAD:  Firecrawl-Expert.md    - PascalCase
BAD:  firecrawl_expert.md    - snake_case
BAD:  firecrawlExpert.md     - camelCase
GOOD: firecrawl-expert.md    - kebab-case

BAD:  skills/PythonPatterns/ - PascalCase directory
GOOD: skills/python-pytest-ops/

BAD:  commands/TestGen.md    - PascalCase
GOOD: commands/testgen.md    - Concatenated lowercase

BAD:  VESPER.md              - UPPERCASE
GOOD: vesper.md              - lowercase
```

## Quick Reference

| Component | Pattern | Example |
|-----------|---------|---------|
| Agent | `{domain}-expert.md` | `firecrawl-expert.md` |
| Skill | `{topic}-ops/SKILL.md` | `postgres-ops/SKILL.md` |
| Command | `{action}.md` | `review.md` |
| Rule | `{topic}.md` | `commit-style.md` |
| Output Style | `{personality}.md` | `vesper.md` |
| Hook | `{trigger}-{action}.sh` | `pre-commit-lint.sh` |
