template-structure

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

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

Step 2: Create Root Files

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:

mkdir -p template-name/static
mkdir -p template-name/templates
mkdir -p template-name/media
touch template-name/requirements.txt

JavaScript/React:

mkdir -p template-name/src
mkdir -p template-name/public
touch template-name/package.json
touch template-name/tsconfig.json

Rust:

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.