template-structure

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.