Collection

---
name: template-structure
description: Implement proper directory structure for project templates following established patterns. Use when creating new templates or organizing template directories.
allowed-tools: Bash, Read, Write
---

You are a template structure expert. You implement proper directory hierarchies and file organization for project templates.

## Standard Template Structure

All templates in this repository follow this structure:

```
template-name/
├── .claude/                       # Claude Code configuration
│   ├── commands/                  # Slash commands
│   │   ├── command1.md
│   │   ├── command2.md
│   │   └── ...                   # 8-12 commands recommended
│   ├── agents/                    # Specialized subagents
│   │   ├── agent1.md
│   │   ├── agent2.md
│   │   └── ...                   # 4-6 agents recommended
│   ├── skills/                    # Automated skills
│   │   ├── skill1/
│   │   │   ├── SKILL.md
│   │   │   ├── reference.md      # Optional
│   │   │   ├── examples/         # Optional
│   │   │   ├── templates/        # Optional
│   │   │   └── scripts/          # Optional
│   │   └── skill2/
│   │       └── SKILL.md
│   └── settings.json              # Claude Code settings
├── README.md                      # Template documentation
├── CLAUDE.md                      # Framework context
├── setup_instructions.md          # Setup guide
├── .gitignore                     # Framework-specific
├── .env.example                   # Environment template
└── [framework files]              # Dependency files, config files
```

## Directory Purposes

### .claude/commands/
**Purpose**: Slash commands for quick operations

**Contents**: Markdown files with YAML frontmatter
- One command per file
- Filename: lowercase-with-hyphens.md
- Must have `description` field
- 8-12 commands recommended

**Command categories**:
- Essential: build, test, run, lint
- Development: create-component, install, clean
- Deployment: deploy, validate, build-prod

### .claude/agents/
**Purpose**: Specialized AI assistants

**Contents**: Markdown files with YAML frontmatter
- One agent per file
- Filename: lowercase-with-hyphens.md
- Must have `name` and `description`
- Description should include PROACTIVELY or MUST BE USED
- 4-6 agents recommended

**Agent categories**:
- Security: framework-specific vulnerability detection
- Performance: optimization and profiling
- Testing: test generation
- Expert: deep framework knowledge
- Optional: accessibility, API design, state management

### .claude/skills/
**Purpose**: Automated capabilities triggered by context

**Contents**: Directories with SKILL.md
- One skill per directory
- Directory name: lowercase-letters-numbers-hyphens
- Must have SKILL.md with frontmatter
- Optional: reference.md, examples/, templates/, scripts/
- 2-4 skills recommended

**Skill categories**:
- Patterns: design pattern implementation
- Generation: code/config generation
- Validation: best practices checking

### Root Files

**README.md**:
- Template overview
- What's included
- Quick start
- Commands/agents/skills documentation
- Development workflow
- Troubleshooting
- Resources

**CLAUDE.md**:
- Framework overview and version
- Project structure
- Common commands
- Code conventions
- Best practices
- Security considerations
- Performance patterns
- Testing strategy
- Official docs links

**setup_instructions.md**:
- Prerequisites
- Step-by-step setup
- Environment configuration
- Database setup (if applicable)
- First component creation
- Running tests
- Deployment guide
- Common issues

**.gitignore**:
- Framework-specific patterns
- .env exclusion
- Build/dist exclusion
- .claude/*.local.* exclusion

**.env.example**:
- All environment variables
- Helpful comments
- No actual secrets
- Grouped logically

**.claude/settings.json**:
- Model configuration
- Environment variables
- Permissions
- Hooks (auto-formatting)

## Creating Template Structure

### Step 1: Create Base Directories

```bash
mkdir -p template-name/.claude/commands
mkdir -p template-name/.claude/agents
mkdir -p template-name/.claude/skills
```

### Step 2: Create Root Files

```bash
touch template-name/README.md
touch template-name/CLAUDE.md
touch template-name/setup_instructions.md
touch template-name/.gitignore
touch template-name/.env.example
touch template-name/.claude/settings.json
```

### Step 3: Framework-Specific Structure

Add framework-specific directories and files:

**Python/Django**:
```bash
mkdir -p template-name/static
mkdir -p template-name/templates
mkdir -p template-name/media
touch template-name/requirements.txt
```

**JavaScript/React**:
```bash
mkdir -p template-name/src
mkdir -p template-name/public
touch template-name/package.json
touch template-name/tsconfig.json
```

**Rust**:
```bash
mkdir -p template-name/src
touch template-name/Cargo.toml
```

## File Organization Best Practices

### Commands Organization
- Group related commands in subdirectories if >15 commands
- Example: `.claude/commands/frontend/`, `.claude/commands/backend/`
- Use clear, descriptive filenames

### Agents Organization
- Keep flat structure in `.claude/agents/`
- Use descriptive names: `framework-security.md`, not `security.md`
- One clear specialty per agent

### Skills Organization
- Each skill in its own directory
- Add supporting files as needed:
  - `reference.md` for detailed API docs
  - `examples/` for code samples
  - `templates/` for reusable code templates
  - `scripts/` for helper scripts

### Documentation Organization
- Keep root docs focused and clear
- Use consistent formatting
- Include tables of contents for long docs
- Link between related docs

## Validation Checklist

When implementing template structure:

**Directories**:
- [ ] `.claude/commands/` exists
- [ ] `.claude/agents/` exists
- [ ] `.claude/skills/` exists
- [ ] Framework-specific directories created

**Root Files**:
- [ ] README.md present
- [ ] CLAUDE.md present
- [ ] setup_instructions.md present
- [ ] .gitignore present
- [ ] .env.example present
- [ ] .claude/settings.json present
- [ ] Dependency file present (requirements.txt, package.json, etc.)

**Commands**:
- [ ] 8+ command files
- [ ] All have .md extension
- [ ] All use lowercase-with-hyphens naming
- [ ] All have YAML frontmatter with description

**Agents**:
- [ ] 4+ agent files
- [ ] All have .md extension
- [ ] All use lowercase-with-hyphens naming
- [ ] All have YAML frontmatter with name and description

**Skills**:
- [ ] 2+ skill directories
- [ ] Each has SKILL.md
- [ ] All use proper naming convention
- [ ] All have YAML frontmatter

**Consistency**:
- [ ] Follows django-template pattern
- [ ] Naming conventions consistent
- [ ] File structure logical
- [ ] Documentation complete

## Common Mistakes to Avoid

❌ **Inconsistent naming**: Using CamelCase or underscores instead of lowercase-with-hyphens

❌ **Missing required files**: Forgetting README.md, CLAUDE.md, or setup_instructions.md

❌ **Insufficient commands**: Having fewer than 8 commands (template feels incomplete)

❌ **Vague agent names**: Using "helper.md" instead of specific names like "security-auditor.md"

❌ **Flat skill structure**: Putting SKILL.md in `.claude/skills/` instead of a subdirectory

❌ **Missing .env.example**: Users won't know what environment variables are needed

❌ **Generic .gitignore**: Not including framework-specific exclusions

## Framework-Specific Considerations

### Python Projects
- Include pytest.ini or setup.cfg if using pytest
- Add requirements-dev.txt for development dependencies
- Consider pipfile if using pipenv

### JavaScript/TypeScript Projects
- Include package-lock.json or yarn.lock (or note in .gitignore)
- Add tsconfig.json for TypeScript
- Include .eslintrc and .prettierrc for code quality
- Add jest.config.js if using Jest

### Rust Projects
- Include Cargo.lock (or note when to commit/ignore)
- Add .cargo/config.toml for custom build configuration
- Include rust-toolchain.toml for version pinning

### Go Projects
- Include go.mod and go.sum
- Add .golangci.yml for linting
- Include Makefile for common operations

## Implementation Process

1. **Create base structure**: Directories and placeholder files
2. **Add framework files**: Dependencies, configurations
3. **Generate commands**: Based on framework workflows
4. **Create agents**: Based on framework needs
5. **Develop skills**: Based on common patterns
6. **Write documentation**: Complete all root files
7. **Validate structure**: Check against standards

This skill ensures all templates follow consistent, comprehensive structure patterns.