init-bdd-project Skill

Purpose

This skill automates the complete initialization of a BDD-based CLI project following best practices outlined in the Universal BDD Guide. It creates a production-ready project structure with:

• •Complete directory layout (src/, tests/, features/)
• •Configured pyproject.toml with all necessary dependencies
• •Behave environment setup with domain-specific hooks
• •Template feature files based on the BDD workflow
• •Pre-configured tooling (ruff, mypy, pytest, behave)
• •.gitignore with standard exclusions

When to Use This Skill

Use this skill when:

• •Starting a new CLI application project
• •You want to use BDD/Gherkin specifications with Behave
• •You need a structured, test-driven development approach
• •You're building tools for data processing, API clients, file management, or system automation
• •You want industry best practices baked in from day one

For AI Agents: How to Invoke This Skill

Skill Location

This skill should be installed in one of these locations:

• •User's Claude Code skills directory: ~/.claude/skills/init-bdd-project/
• •Project-local skills directory: {project_root}/.claude/skills/init-bdd-project/
• •Working directory: {cwd}/init-bdd-project/

Determining the Skill Path

Before invoking, check if the skill exists:

# Check common locations
if [ -f ~/.claude/skills/init-bdd-project/scripts/init_project.py ]; then
    SKILL_PATH=~/.claude/skills/init-bdd-project
elif [ -f ./.claude/skills/init-bdd-project/scripts/init_project.py ]; then
    SKILL_PATH=./.claude/skills/init-bdd-project
elif [ -f ./init-bdd-project/scripts/init_project.py ]; then
    SKILL_PATH=./init-bdd-project
else
    echo "Error: init-bdd-project skill not found"
    exit 1
fi

Invocation Command

Use one of these approaches:

Option 1: Using uv run (recommended)

uv run python ${SKILL_PATH}/scripts/init_project.py \
    --name "my-project" \
    --framework "click" \
    --domain "data processing" \
    --integrations "api,files"

Option 2: Direct Python (if uv not available)

python3 ${SKILL_PATH}/scripts/init_project.py \
    --name "my-project" \
    --framework "click" \
    --domain "data processing" \
    --integrations "api,files"

Option 3: Using absolute path

python3 /Users/username/.claude/skills/init-bdd-project/scripts/init_project.py \
    --name "my-project" \
    --framework "click"

Working Directory Considerations

• •The script creates the project directory relative to where it's executed
• •By default, it creates in the current working directory
• •Use --path flag to specify a different base directory:

uv run python ${SKILL_PATH}/scripts/init_project.py \
    --name "my-project" \
    --framework "typer" \
    --path "/Users/username/projects"

Prerequisites Check

The script will automatically check for:

• •✅ uv command availability
• •✅ Python 3.11+ version
• •⚠️ git (warning only, not fatal)

If prerequisites are missing, the script will fail fast with installation instructions.

Complete Agent Workflow

Here's the complete flow an AI agent should follow:

# 1. Locate the skill
SKILL_PATH="./init-bdd-project"  # Adjust based on actual location

# 2. Gather user requirements (see Required Inputs section below)
PROJECT_NAME="data-validator"
FRAMEWORK="click"
DOMAIN="data validation tool"
INTEGRATIONS="files"

# 3. Invoke the skill
uv run python ${SKILL_PATH}/scripts/init_project.py \
    --name "${PROJECT_NAME}" \
    --framework "${FRAMEWORK}" \
    --domain "${DOMAIN}" \
    --integrations "${INTEGRATIONS}"

# 4. Navigate to created project
cd "${PROJECT_NAME}"

# 5. Initialize git repository
git init
git add .
git commit -m "Initial project structure from init-bdd-project skill"

# 6. Set up Python environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

# 7. Verify installation
uv run ruff check .
uv run mypy src/
uv run pytest tests/
uv run behave

# 8. Report completion to user
echo "✓ Project ${PROJECT_NAME} initialized successfully!"

Error Handling

The script may raise these errors:

Required Inputs

The skill will gather the following information from you:

1. •

   project_name (required): The name of your project (e.g., "data-validator", "api-client")

   • •Must be a valid Python package name (lowercase, underscores allowed)
   • •Will be used for directory names and package structure
2. •

   cli_framework (required): Choose one:

   • •click: Full-featured, decorator-based CLI framework (most popular)
   • •typer: Modern, type-hint based CLI framework (Click-powered)
   • •argparse: Python standard library (minimal dependencies)
3. •

   domain (optional): Domain/purpose of your CLI tool:

   • •Examples: "data processing", "API client", "file converter", "deployment tool"
   • •Helps customize template features and documentation
   • •If not provided, creates generic templates
4. •

   integrations (optional): List of external integrations your CLI will use:

   • •api: HTTP/REST API integrations (adds httpx, responses for mocking)
   • •database: Database operations (adds sqlalchemy, psycopg2)
   • •files: File processing beyond basic I/O (adds pypdf2, python-magic)
   • •data: Data analysis/transformation (adds pandas, numpy)
   • •Can select multiple (e.g., ["api", "files"])

Output

Creates a complete project structure:

{project_name}/
├── src/
│   └── {project_name}/
│       ├── __init__.py
│       ├── core/              # Domain models
│       ├── infrastructure/    # External integrations
│       ├── services/          # Business logic
│       ├── cli/              # CLI interface
│       └── config/           # Configuration
├── tests/
│   ├── unit/                 # pytest unit tests
│   └── integration/          # pytest integration tests
├── features/                 # Behave BDD tests
│   ├── 01_foundation.feature
│   ├── environment.py
│   ├── behave.ini
│   └── steps/
│       ├── __init__.py
│       └── common_steps.py
├── pyproject.toml           # Complete with dependencies
├── README.md                # Project documentation
├── .gitignore              # Standard exclusions
└── .python-version         # Python version specification

Implementation Steps

Step 1: Gather Requirements

Ask the user for required inputs if not already provided:

• •project_name (validate it's a valid Python package name)
• •cli_framework (present as a choice: click, typer, or argparse)
• •domain (optional, ask for a brief description)
• •integrations (optional, multi-select from: api, database, files, data)

Step 2: Validate Inputs

• •Ensure project_name is valid (lowercase, no hyphens, valid Python identifier)
• •Ensure the target directory doesn't already exist
• •Convert project_name to snake_case if needed

Step 3: Create Directory Structure

Execute the project initialization script. See the "For AI Agents: How to Invoke This Skill" section above for detailed invocation instructions.

# Determine skill path (see agent invocation section for details)
SKILL_PATH="./init-bdd-project"  # Or use absolute path

# Execute the initialization
uv run python ${SKILL_PATH}/scripts/init_project.py \
  --name "{project_name}" \
  --framework "{cli_framework}" \
  --domain "{domain}" \
  --integrations "{integrations}"

Note: The script will automatically:

• •Check prerequisites (uv, Python 3.11+)
• •Validate project name
• •Create all directory structures
• •Generate configuration files
• •Set up Behave environment
• •Create template features

Step 4: Initialize Git Repository

cd {project_name}
git init
git add .
git commit -m "Initial project structure from init-bdd-project skill"

Step 5: Set up Python Environment

cd {project_name}
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv sync

Step 6: Verify Installation

Run basic checks to ensure everything is set up correctly:

uv run ruff check .        # Should pass (no code yet)
uv run mypy src/          # Should pass
uv run pytest tests/      # Should pass (no tests yet)
uv run behave             # Should show 0 scenarios

Step 7: Report Completion

Provide the user with:

• •Summary of what was created
• •Next steps for development
• •Link to BDD_IMPLEMENTATION_GUIDE.md for workflow guidance

Example Usage

Example 1: Simple CLI Tool

User: "I need to create a new CLI tool for validating data files"

Agent: <uses init-bdd-project skill>
  - Asks for project name: "data-validator"
  - Asks for CLI framework: "click"
  - Asks for domain: "data validation"
  - Asks for integrations: ["files"]

Agent: <creates complete project structure>

Output:
  ✓ Created data-validator/ with complete BDD structure
  ✓ Installed dependencies: click, pydantic, behave, pytest, ruff, mypy
  ✓ Added file processing dependencies: pypdf2, python-magic
  ✓ Created template features for data validation domain
  ✓ Initialized git repository
  ✓ All checks passing

Next steps:
  1. cd data-validator
  2. Review features/01_foundation.feature
  3. Follow BDD workflow in BDD_IMPLEMENTATION_GUIDE.md

Example 2: API Client

User: "Create a new project for a REST API client that needs database caching"

Agent: <uses init-bdd-project skill>
  - project_name: "api-client"
  - cli_framework: "typer"
  - domain: "REST API client with caching"
  - integrations: ["api", "database"]

Agent: <creates complete project structure>

Output:
  ✓ Created api-client/ with typer framework
  ✓ Added HTTP client dependencies: httpx, responses
  ✓ Added database dependencies: sqlalchemy, psycopg2
  ✓ Created template features for API client workflows
  ✓ Environment configured with API mocking and database test isolation

Next steps:
  1. cd api-client
  2. Define your API integration in features/04_external_integrations.feature
  3. Implement using the BDD red-green-refactor cycle

Common Patterns

After Creating a Project

1. •Review Generated Features: Check features/01_foundation.feature for initial scenarios
2. •Customize Environment: Edit features/environment.py for domain-specific setup
3. •Add Dependencies: Run uv add <package> for additional needs
4. •Start Development: Tag first scenario as @wip and begin BDD cycle

Integration with Other Skills

This skill works well with:

• •bdd-cycle: Implement individual scenarios
• •generate-step-definitions: Create step definitions from features
• •setup-behave-env: Further customize the Behave environment
• •review-gherkin-quality: Validate your feature files

Troubleshooting

"Project directory already exists"

• •Choose a different project name
• •Remove the existing directory if it was a failed attempt
• •Use --force flag to override (not recommended)

"Invalid project name"

• •Use lowercase letters, numbers, and underscores only
• •Start with a letter
• •No hyphens (hyphens are fine for the skill name, but not Python packages)

"uv command not found"

• •Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• •Restart your shell
• •Verify: uv --version

Dependencies fail to install

• •Check Python version (3.11+ recommended)
• •Ensure uv is up to date: uv self update
• •Check internet connection
• •Try: uv sync --refresh

Technical Details

Dependencies Added by Default

Core Dependencies:

• •pydantic: Data validation and settings
• •structlog: Structured logging
• •rich: Terminal formatting
• •pyyaml: Configuration files
• •toml: TOML support

CLI Framework (one of):

• •click
• •typer
• •(argparse is stdlib, no install needed)

Development Dependencies:

• •pytest: Unit testing
• •pytest-cov: Coverage reporting
• •pytest-mock: Mocking support
• •mypy: Static type checking
• •ruff: Linting and formatting
• •behave: BDD testing
• •freezegun: Time mocking for tests

Integration-Specific (based on selections):

• •api: httpx, responses
• •database: sqlalchemy, psycopg2-binary
• •files: pypdf2, python-magic-bin
• •data: pandas, numpy

Project Structure Philosophy

The structure follows:

• •XDG Base Directory: Standard file locations
• •src/ layout: Prevents accidental imports
• •Domain-Driven Design: Separate core, infrastructure, services
• •Test Pyramid: Unit > Integration > BDD
• •Progressive Feature Files: Numbered for implementation order

Best Practices

1. •Start Simple: Begin with foundation features, add complexity incrementally
2. •Follow BDD Cycle: Red → Green → Refactor for each scenario
3. •Tag Properly: Use @wip, @passing, @failing to track progress
4. •Document as You Go: Update README with actual usage
5. •Commit Often: Each passing scenario is a commit-worthy milestone

Reference

This skill implements the initialization strategy from:

• •BDD_IMPLEMENTATION_GUIDE.md: Part 2 (Project Setup and Structure)
• •agentskills.io: Anthropic Skills Specification

For the complete BDD workflow after initialization, refer to BDD_IMPLEMENTATION_GUIDE.md sections on:

• •Part 3: Setting Up Behave
• •Part 4: Writing Step Definitions
• •Part 5: Implementation Strategy