🚀 AI Development Boilerplate

A comprehensive boilerplate for AI-enhanced development using Claude Code, including MCP servers, custom skills, and technical specification templates.

🎯 What's Included

• ✅ MCP Servers: Two ready-to-use MCPs (Jest + Azure Boards) with setup scripts
• ✅ Custom Skills: Automate workflows with intelligent behaviors
• ✅ Spec Templates: Comprehensive technical specification templates
• ✅ Documentation: Complete guides and examples
• ✅ Best Practices: Proven patterns and conventions

📦 Project Structure

ai-boilerplate/
├── .claude/                    # Claude Code configuration
│   ├── skills/                # Custom skills
│   │   ├── README.md         # Skills documentation
│   │   ├── EXAMPLES.md       # Skill examples
│   │   ├── example-skill.json # Template skill
│   │   └── setup-skills.sh   # Setup script
│   ├── SETUP_GUIDE.md        # Complete setup guide
│   ├── settings.local.json   # Local settings
│   └── .gitignore           # Git ignore for Claude files
├── mcp-servers/               # MCP servers
│   ├── jest-mcp/             # Jest test runner MCP (ready to use)
│   ├── azure-boards-mcp/     # Azure Boards integration MCP (ready to use)
│   └── README.md             # MCP documentation
├── specs/                     # Technical specifications
│   ├── README.md             # Specs guide
│   └── TEMPLATE.md           # Spec template
├── CLAUDE.md                  # Instructions for Claude Code
└── README.md                  # This file

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• Claude Code installed
• Git (optional)

Installation

1. Clone or copy this boilerplate:

# Clone
git clone https://github.com/paulohb-dev/ai-boilerplate 
copy to your project folder

2. Setup Skills (optional):

rename claude folder to .claude
cd .claude/skills
./setup-skills.sh

3. Setup MCP Servers (optional, choose what you need):

# Jest MCP - for running tests via conversation
cd mcp-servers/jest-mcp
./setup.sh

# Azure Boards MCP - for project management integration
cd mcp-servers/azure-boards-mcp
cp .env.example .env
# Edit .env with your credentials
./setup.sh

4. Restart Claude Code

5. Start using!

"What tools and skills are available?"

📚 Documentation

Core Documentation

• .claude/SETUP_GUIDE.md - Complete setup guide for Claude Code integration
• .claude/skills/README.md - Skills documentation and usage
• .claude/skills/EXAMPLES.md - Skill examples and templates
• mcp-servers/README.md - MCP servers guide
• specs/README.md - Technical specifications guide
• specs/TEMPLATE.md - Spec template
• CLAUDE.md - Instructions for Claude Code

Quick Links

• How to create a new skill
• How to create an MCP server
• How to write a spec

🎓 Usage Examples

Using Skills

Skills automate common workflows. For example:

You: "Create a new component Button"

Claude:
1. Creates the component
2. [skill activated] Automatically runs related tests
3. [skill activated] Generates documentation
4. Reports results

Using MCP Servers

MCPs extend Claude's capabilities with custom tools:

You: "Run the project tests"

Claude:
[Uses test-runner MCP]
✅ 25/25 tests passed
📊 Coverage: 87%

Using Specs

Specs document features comprehensively:

You: "Generate a technical spec for user authentication"

Claude:
[Uses specs/TEMPLATE.md]
Creates detailed spec including:
- Acceptance criteria
- BDD scenarios
- Technical architecture
- Test templates

🛠️ Customization

Adding Your Own Skills

1. Copy example-skill.json as a template
2. Customize triggers and workflow
3. Test and iterate
4. Document in EXAMPLES.md

See Skills Examples for detailed guide.

Creating MCP Servers

1. Create folder in mcp-servers/
2. Implement using MCP SDK
3. Add documentation and setup script
4. Configure in ~/.claude/settings.json

See MCP Guide for detailed instructions.

Writing Technical Specs

1. Copy specs/TEMPLATE.md
2. Fill in all sections
3. Review and validate
4. Use for implementation

See Specs Guide for best practices.

📋 What You Can Build

Skills Ideas

• ✅ Auto-test runner after code changes
• ✅ Auto-documentation generator
• ✅ Pre-commit validation
• ✅ Bundle size monitor
• ✅ Security scanner
• ✅ Code formatter

MCP Ideas

• ✅ Test runner (Jest, Vitest, etc.)
• ✅ Database query tool
• ✅ API tester
• ✅ Git operations
• ✅ Cloud services integration
• ✅ Task management (Jira, Azure Boards)

Spec Types

• ✅ Feature specifications
• ✅ API documentation
• ✅ Architecture decisions
• ✅ Bug fix documentation
• ✅ Refactoring plans

🔧 Configuration

Claude Code Settings

Edit ~/.claude/settings.json:

{
  "skills": {
    "projectSkills": [
      "/absolute/path/to/ai-boilerplate/.claude/skills"
    ]
  },
  "mcpServers": {
    "your-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ai-boilerplate/mcp-servers/your-mcp/index.js"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/ai-boilerplate"
      }
    }
  }
}

Important: Use absolute paths!

Project Settings

Edit .claude/settings.local.json for project-specific permissions:

{
  "permissions": {
    "allow": [
      "Bash(grep:*)"
    ]
  }
}

🐛 Troubleshooting

Skills Not Working

1. Check ~/.claude/settings.json has correct path
2. Ensure skills have "enabled": true
3. Restart Claude Code
4. Check logs in ~/.claude/logs/

MCP Not Found

1. Verify path in settings.json is absolute
2. Check dependencies are installed (npm install)
3. Test MCP directly: node mcp-servers/your-mcp/index.js
4. Restart Claude Code

Setup Script Fails

1. Ensure you have execute permissions: chmod +x setup.sh
2. Check Node.js version: node --version (need >=18)
3. Install dependencies manually: npm install

See Setup Guide for more troubleshooting.

🤝 Contributing

This is a boilerplate project - fork it and make it your own!

Ideas for improvements:

• Add more example skills
• Create sample MCP servers
• Improve documentation
• Add more spec templates

📚 Resources

Official Documentation

• Claude Code
• Model Context Protocol
• MCP SDK

Community

• Awesome MCP
• MCP Servers

📄 License

MIT License - feel free to use this boilerplate for any project!

🎉 Credits

This boilerplate includes patterns and best practices inspired by real-world projects using Claude Code.

---

Version: 1.0.0 Last Updated: March 2026 Status: Ready to use

---

🚦 Next Steps

1. ✅ Read the Setup Guide
2. ✅ Explore Skills Examples
3. ✅ Create your first skill or MCP
4. ✅ Write a technical spec using the template
5. ✅ Customize for your project needs

Happy coding with AI! 🤖