claude-code-templates

CLI tool for configuring and monitoring Claude Code

30,218 stars Python Markdown Skills API Spec #anthropic#anthropic-claude#claude#claude-code
AI Prompts & Specs

Repository: davila7/claude-code-templates


Stars: 24675

CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Node.js CLI tool for managing Claude Code components (agents, commands, MCPs, hooks, settings) with a static website for browsing and installing components. The project includes Vercel API endpoints for download tracking and Discord integration.

Essential Commands

bash
Development

npm install                    # Install dependencies
npm test                       # Run tests
npm version patch|minor|major  # Bump version
npm publish                    # Publish to npm
Component catalog

python scripts/generate_components_json.py  # Update docs/components.json
API testing

cd api && npm test             # Test API endpoints before deploy
vercel --prod                  # Deploy to production

Security Guidelines

⛔ CRITICAL: NEVER Hardcode Secrets or IDs

NEVER write API keys, tokens, passwords, project IDs, org IDs, or any identifier in code. This includes Vercel project/org IDs, Supabase URLs, Discord IDs, database connection strings, and any other infrastructure identifier. ALL must go in .env.

javascript
// ❌ WRONG
const API_KEY = "AIzaSy...";
// ✅ CORRECT
const API_KEY = process.env.GOOGLE_API_KEY;

When creating scripts with API keys:
1. Use process.env (Node.js) or os.environ.get() (Python)
2. Load from .env file using dotenv
3. Add variable to .env.example with placeholder
4. Verify .env is in .gitignore

If you accidentally commit a secret:
1. Revoke the key IMMEDIATELY
2. Generate new key
3. Update .env
4. Old key is compromised forever (git history)

Component System

Component Types

Agents (600+) - AI specialists for development tasks
Commands (200+) - Custom slash commands for workflows
MCPs (55+) - External service integrations
Settings (60+) - Claude Code configuration files
Hooks (39+) - Automation triggers
Templates (14+) - Complete project configurations

Installation Patterns

bash
Single component

npx claude-code-templates@latest --agent frontend-developer
npx claude-code-templates@latest --command setup-testing
npx claude-code-templates@latest --hook automation/simple-notifications
Batch installation

npx claude-code-templates@latest --agent security-auditor --command security-audit --setting read-only-mode
Interactive mode

npx claude-code-templates@latest

Component Development

#### Adding New Components

CRITICAL: Use the component-reviewer agent for ALL component changes

When adding or modifying components, you MUST use the component-reviewer subagent to validate the component before committing:

text
Use the component-reviewer agent to review [component-path]

Component Creation Workflow:

1. Create component file in cli-tool/components/{type}/{category}/{name}.md
2. Use descriptive hyphenated names (kebab-case)
3. Include clear descriptions and usage examples
4. REVIEW with component-reviewer agent (validates format, security, naming)
5. Fix any issues identified by the reviewer
6. Run python scripts/generate_components_json.py to update catalog

The component-reviewer agent checks:
- ✅ Valid YAML frontmatter and required fields
- ✅ Proper kebab-case naming conventions
- ✅ No hardcoded secrets (API keys, tokens, passwords)
- ✅ Relative paths only (no absolute paths)
- ✅ Supporting files exist (for hooks with scripts)
- ✅ Clear, specific descriptions
- ✅ Correct category placement
- ✅ Security best practices

Example Usage:

text
After creating a new agent

Use the component-reviewer agent to review cli-tool/components/agents/development-team/react-expert.md
Before committing hook changes

Use the component-reviewer agent to review cli-tool/components/hooks/git/prevent-force-push.json
For PR reviews with multiple components

Use the component-reviewer agent to review all modified components in cli-tool/components/

The agent will provide prioritized feedback:
- ❌ Critical Issues: Must fix before merge (security, missing fields)
- ⚠️ Warnings: Should fix (clarity, best practices)
- 📋 Suggestions: Nice to have improvements

#### Statuslines with Python Scripts

Statuslines can reference Python scripts that are auto-downloaded to .claude/scripts/:

javascript
// In src/index.js:installIndividualSetting()
if (settingName.includes('statusline/')) {
  const pythonFileName = settingName.split('/')[1] + '.py';
  const pythonUrl = githubUrl.replace('.json', '.py');
  additionalFiles['.claude/scripts/' + pythonFileName] = {
    content: pythonContent,
    executable: true
  };
}

Publishing Workflow

bash
1. Update component catalog

python scripts/generate_components_json.py
2. Run tests

npm test
3. Check current npm version and align local version

npm view claude-code-templates version  # check latest on registry
Edit package.json version to be one patch above the registry version
4. Commit version bump and push

git add package.json && git commit -m "chore: Bump version to X.Y.Z"
git push origin main
5. Publish to npm (requires granular access token with "Bypass 2FA" enabled)

npm config set //registry.npmjs.org/:_authToken=YOUR_GRANULAR_TOKEN
npm publish
npm config delete //registry.npmjs.org/:_authToken  # always clean up after
6. Tag the release

git tag vX.Y.Z && git push origin vX.Y.Z
7. Deploy website

vercel --prod

npm Publishing Notes:
- Classic npm tokens were revoked Dec 2025. Use granular access tokens from npmjs.com/settings/~/tokens
- The token must have Read and Write permissions for claude-code-templates and "Bypass 2FA" enabled
- Always remove the token from npm config after publishing (npm config delete)
- The local package.json version may drift from npm if published from CI — always check npm view claude-code-templates version first
- Never hardcode or commit tokens

API Architecture

Critical Endpoints

API endpoints live as Astro API routes in dashboard/src/pages/api/:

/api/track-download-supabase (CRITICAL)
- Tracks component downloads for analytics
- Used by CLI on every installation
- Database: Supabase (component_downloads table)

/api/discord/interactions
- Discord bot slash commands
- Features: /search, /info, /install, /popular

/api/claude-code-check
- Monitors Claude Code releases
- Vercel Cron: every 30 minutes
- Database: Neon (claude_code_versions, claude_code_changes, discord_notifications_log, monitoring_metadata tables)

Shared API Libraries

- dashboard/src/lib/api/cors.ts — CORS headers, corsResponse(), jsonResponse()
- dashboard/src/lib/api/neon.ts — Neon client factory
- dashboard/src/lib/api/auth.ts — Clerk JWT verification
- dashboard/src/lib/api/changelog-parser.ts — Claude Code changelog parser

Emergency Rollback

bash
vercel ls                              # List deployments
vercel promote <previous-deployment>   # Rollback

Cloudflare Workers

The cloudflare-workers/ directory contains Cloudflare Worker projects that run independently from Vercel.

docs-monitor

Monitors https://code.claude.com/docs for changes every hour and sends Telegram notifications.

bash
cd cloudflare-workers/docs-monitor
npm run dev          # Local dev
npx wrangler deploy  # Deploy

pulse (Weekly KPI Report)

Collects metrics from GitHub, Discord, Supabase, Vercel, and Google Analytics every Sunday at 14:00 UTC and sends a consolidated report via Telegram.

Architecture: Single index.js file (no npm dependencies at runtime). All source collectors, formatter, and Telegram sender in one file.

Cron: 0 14 0 (Sundays 14:00 UTC / 11:00 AM Chile)

bash
cd cloudflare-workers/pulse
npm run dev          # Local dev
npx wrangler deploy  # Deploy
Manual trigger

curl -X POST https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger \
  -H "Authorization: Bearer $TRIGGER_SECRET"
Test single source

curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?source=github" \
  -H "Authorization: Bearer $TRIGGER_SECRET"
Dry run (no Telegram)

curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?send=false" \
  -H "Authorization: Bearer $TRIGGER_SECRET"

Secrets (Cloudflare):

bash
TELEGRAM_BOT_TOKEN          # Shared with docs-monitor
TELEGRAM_CHAT_ID            # Shared with docs-monitor
GITHUB_TOKEN                # GitHub PAT (public_repo scope)
SUPABASE_URL                # Supabase project URL
SUPABASE_SERVICE_ROLE_KEY   # Supabase service role key
DISCORD_BOT_TOKEN           # Discord bot token
DISCORD_GUILD_ID            # Discord server ID
VERCEL_TOKEN                # Vercel personal access token (optional)
VERCEL_PROJECT_ID           # Vercel project ID (optional)
TRIGGER_SECRET              # For manual /trigger endpoint
GA_PROPERTY_ID              # GA4 property ID (optional)
GA_SERVICE_ACCOUNT_JSON     # Base64 service account (optional)

Graceful degradation: Each source catches its own errors. Missing secrets or API failures show ⚠️ Unavailable instead of crashing the report.

Dashboard (www.aitmpl.com)

Astro + React + Tailwind dashboard serving both www.aitmpl.com and app.aitmpl.com. Clerk auth for user collections. Source lives in dashboard/. All API endpoints are Astro API routes in the same project.

Architecture

- Framework: Astro 5 with React islands, Tailwind v4, output: 'server'
- Auth: Clerk (window.Clerk global, no ClerkProvider per island)
- Data: components.json and trending-data.json served from dashboard/public/ (same-origin)
- APIs: All endpoints in dashboard/src/pages/api/ (Astro API routes, no separate serverless project)

Featured partner integrations shown on the dashboard homepage. Two files to edit:

dashboard/src/lib/constants.ts — FEATURED_ITEMS array. Each entry has:
- name, description, logo, url (/featured/slug), tag, tagColor, category
- ctaLabel, ctaUrl, websiteUrl
- installCommand — shown in the sidebar Quick Install box
- metadata — key/value pairs shown in the Details sidebar (e.g. Components: '8')
- links — sidebar links list

dashboard/src/pages/featured/[slug].astro — Content for each slug rendered via {slug === 'brightdata' && (...)} blocks. Each block contains the full HTML content for that partner page.

When adding a skill to a featured page:
1. Add a new card <div class="flex gap-3 ..."> inside the Skills Layer section of the relevant {slug === '...'} block
2. Update installCommand in constants.ts to include the new skill
3. Increment metadata.Components count in constants.ts

Current featured slugs: brightdata, neon-instagres, claudekit, braingrid

Vercel Project Setup

Single Vercel project serves all domains:

| Project | Domains | Root Directory |
|---------|---------|----------------|
| aitmpl-dashboard | www.aitmpl.com, aitmpl.com (redirect), app.aitmpl.com | dashboard |

The legacy root project (aitmpl) is archived — only its .vercel.app subdomain remains.

Deployment

ALWAYS use the deployer agent (.claude/agents/deployer.md) for all deployments. It runs pre-deploy checks (auth, git status, API tests) and handles the full pipeline safely. Never deploy manually.

bash
npm run deploy             # Deploy www + app.aitmpl.com
npm run deploy:dashboard   # Same as above

CI/CD: Pushes to main auto-deploy via GitHub Actions (.github/workflows/deploy.yml):
- Changes in dashboard/ trigger deploy

Required GitHub Secrets (Settings > Secrets > Actions):
- VERCEL_TOKEN — Vercel personal access token
- VERCEL_ORG_ID — Vercel org/team ID
- VERCEL_DASHBOARD_PROJECT_ID — Project ID for aitmpl-dashboard

Environment Variables (Vercel)

bash
Clerk

PUBLIC_CLERK_PUBLISHABLE_KEY=xxx
CLERK_SECRET_KEY=xxx
Data

PUBLIC_COMPONENTS_JSON_URL=/components.json
GitHub OAuth

PUBLIC_GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
Supabase (download tracking)

SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxx
Neon Database

NEON_DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
Discord

DISCORD_APP_ID=xxx
DISCORD_BOT_TOKEN=xxx
DISCORD_PUBLIC_KEY=xxx
DISCORD_WEBHOOK_URL_CHANGELOG=https://discord.com/api/webhooks/xxx

Known Issues & Solutions

Node v24 breaks fs.writeFileSync on Vercel
- Node v24 has a bug with writeFileSync in Vercel's build environment
- Solution: Dashboard project is pinned to Node 22.x (set via Vercel API/dashboard)

Vercel CLI ignores local .vercel/project.json
- The CLI often resolves to the parent directory's project. Use VERCEL_ORG_ID and VERCEL_PROJECT_ID env vars to force the correct project.

Local Development

bash
cd dashboard
npm install
npx astro dev --port 4321   # Dashboard + APIs at http://localhost:4321

Data Files

Component Catalog

- docs/components.json — Generated catalog (source of truth)
- dashboard/public/components.json — Copy served by the dashboard
- dashboard/public/trending-data.json — Trending/download stats

Data Flow

1. scripts/generate_components_json.py scans cli-tool/components/
2. Generates docs/components.json with embedded content
3. Copy to dashboard/public/components.json for the dashboard to serve
4. Dashboard loads JSON and renders component cards
5. Download tracking via /api/track-download-supabase

Legacy Static Site (docs/)

The docs/ directory contains the old static HTML site (no longer deployed to www). Blog articles in docs/blog/ are still referenced externally.

Blog Article Creation

Use the CLI skill to create blog articles:

bash
/create-blog-article @cli-tool/components/{type}/{category}/{name}.json

This automatically:
1. Generates AI cover image
2. Creates HTML with SEO optimization
3. Updates docs/blog/blog-articles.json

Code Standards

Path Handling


- Use relative paths: .claude/scripts/, .claude/hooks/
- Never hardcode absolute paths or home directories
- Use path.join() for cross-platform compatibility

Naming Conventions


- Files: kebab-case.js, PascalCase.js (for classes)
- Functions/Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Components: hyphenated-names

Error Handling


- Use try/catch for async operations
- Provide helpful error messages
- Log errors with context
- Implement fallback mechanisms

Testing

bash
npm test                 # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Aim for 70%+ test coverage. Test critical paths and error handling.

Common Issues

API endpoint returns 404 after deploy
- API routes must be in dashboard/src/pages/api/ as Astro API routes
- Export named HTTP methods: export const POST: APIRoute, export const GET: APIRoute

Download tracking not working
- Check Vercel logs: vercel logs aitmpl.com --follow
- Verify environment variables in Vercel dashboard
- Test endpoint manually with curl

Components not updating on website
- Run python scripts/generate_components_json.py
- Copy docs/components.json to dashboard/public/components.json
- Deploy and clear browser cache

Important Notes

- Component catalog: Always regenerate after adding/modifying components
- API tests: Required before production deploy (breaks download tracking)
- Secrets: Never commit API keys (use environment variables)
- Paths: Use relative paths for all project files
- Backwards compatibility: Don't break existing component installations


README.md

![npm version](https://www.npmjs.com/package/claude-code-templates)
![npm downloads](https://www.npmjs.com/package/claude-code-templates)
![License: MIT](https://opensource.org/licenses/MIT)
![PRs Welcome](CONTRIBUTING.md)
![Sponsored by Z.AI](https://z.ai/subscribe?ic=8JVLJQFSKB&utm_source=github&utm_medium=badge&utm_campaign=readme)
![Claude for Open Source](https://claude.com/contact-sales/claude-for-oss)
![Neon Open Source Program](https://get.neon.com/4eCjZDz)
![Buy Me A Coffee](https://buymeacoffee.com/daniavila)
![GitHub stars](https://github.com/davila7/claude-code-templates)

<p align="center">
<a href="https://trendshift.io/repositories/15113" target="_blank">
<img src="https://trendshift.io/api/badge/repositories/15113" alt="davila7%2Fclaude-code-templates | Trendshift" style="width: 200px; height: 40px;" width="125" height="40"/>
</a>
<br />
<br />
<a href="https://vercel.com/oss">
<img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge.svg" />
</a>
&nbsp;&nbsp;
<a href="https://get.neon.com/4eCjZDz">
<img alt="Neon Open Source Program" src="https://img.shields.io/badge/Neon-Open%20Source%20Program-00E599?style=for-the-badge" />
</a>
&nbsp;&nbsp;
<a href="https://claude.com/contact-sales/claude-for-oss">
<img alt="Claude for Open Source" src="docs/claude-oss-badge.svg" height="48" />
</a>
</p>

---

🧪 NEW: Dashboard — Explore components, manage collections, and track installations at www.aitmpl.com. Currently in beta — feedback welcome!

Claude Code Templates (aitmpl.com)

Ready-to-use configurations for Anthropic's Claude Code. A comprehensive collection of AI agents, custom commands, settings, hooks, external integrations (MCPs), and project templates to enhance your development workflow.

Browse & Install Components and Templates

Browse All Templates - Interactive web interface to explore and install 100+ agents, commands, settings, hooks, and MCPs.

<img width="1049" height="855" alt="Screenshot 2025-08-19 at 08 09 24" src="https://github.com/user-attachments/assets/e3617410-9b1c-4731-87b7-a3858800b737" />

🚀 Quick Installation

bash
Install a complete development stack

npx claude-code-templates@latest --agent development-team/frontend-developer --command testing/generate-tests --mcp development/github-integration --yes
Browse and install interactively

npx claude-code-templates@latest
Install specific components

npx claude-code-templates@latest --agent development-tools/code-reviewer --yes
npx claude-code-templates@latest --command performance/optimize-bundle --yes
npx claude-code-templates@latest --setting performance/mcp-timeouts --yes
npx claude-code-templates@latest --hook git/pre-commit-validation --yes
npx claude-code-templates@latest --mcp database/postgresql-integration --yes

What You Get

| Component | Description | Examples |
|-----------|-------------|----------|
| 🤖 Agents | AI specialists for specific domains | Security auditor, React performance optimizer, database architect |
| ⚡ Commands | Custom slash commands | /generate-tests, /optimize-bundle, /check-security |
| 🔌 MCPs | External service integrations | GitHub, PostgreSQL, Stripe, AWS, OpenAI |
| ⚙️ Settings | Claude Code configurations | Timeouts, memory settings, output styles |
| 🪝 Hooks | Automation triggers | Pre-commit validation, post-completion actions |
| 🎨 Skills | Reusable capabilities with progressive disclosure | PDF processing, Excel automation, custom workflows |

🛠️ Additional Tools

Beyond the template catalog, Claude Code Templates includes powerful development tools:

📊 Claude Code Analytics


Monitor your AI-powered development sessions in real-time with live state detection and performance metrics.

bash
npx claude-code-templates@latest --analytics

💬 Conversation Monitor


Mobile-optimized interface to view Claude responses in real-time with secure remote access.

bash
Local access

npx claude-code-templates@latest --chats
Secure remote access via Cloudflare Tunnel

npx claude-code-templates@latest --chats --tunnel

🔍 Health Check


Comprehensive diagnostics to ensure your Claude Code installation is optimized.

bash
npx claude-code-templates@latest --health-check

🔌 Plugin Dashboard


View marketplaces, installed plugins, and manage permissions from a unified interface.

bash
npx claude-code-templates@latest --plugins

📖 Documentation

📚 docs.aitmpl.com - Complete guides, examples, and API reference for all components and tools.

Contributing

We welcome contributions! Browse existing templates to see what's available, then check our contributing guidelines to add your own agents, commands, MCPs, settings, or hooks.

Please read our Code of Conduct before contributing.

Attribution

This collection includes components from multiple sources:

Scientific Skills:
- K-Dense-AI/claude-scientific-skills by K-Dense Inc. - MIT License (139 scientific skills for biology, chemistry, medicine, and computational research)

Official Anthropic:
- anthropics/skills - Official Anthropic skills (21 skills)
- anthropics/claude-code - Development guides and examples (10 skills)

Community Skills & Agents:
- obra/superpowers by Jesse Obra - MIT License (14 workflow skills)
- alirezarezvani/claude-skills by Alireza Rezvani - MIT License (36 professional role skills)
- wshobson/agents by wshobson - MIT License (48 agents)
- NerdyChefsAI Skills - Community contribution - MIT License (specialized enterprise skills)

Commands & Tools:
- awesome-claude-code by hesreallyhim - CC0 1.0 Universal (21 commands)
- awesome-claude-skills - Apache 2.0 (community skills)
- move-code-quality-skill - MIT License
- cocoindex-claude - Apache 2.0

Each of these resources retains its original license and attribution, as defined by their respective authors.
We respect and credit all original creators for their work and contributions to the Claude ecosystem.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

- 🌐 Browse Templates: aitmpl.com
- 📚 Documentation: docs.aitmpl.com
- 💬 Community: GitHub Discussions
- 🐛 Issues: GitHub Issues

Stargazers over time


![Stargazers over time](https://starchart.cc/davila7/claude-code-templates)

---

⭐ Found this useful? Give us a star to support the project!

![Buy Me A Coffee](https://buymeacoffee.com/daniavila)