aitmpl.com Template Downloader

Download Claude Code templates from aitmpl.com using GitHub API for real-time data.

Architecture

aitmpl-downloader/
├── SKILL.md                 # This file - overview and commands
├── scripts/
│   ├── download.py          # Download script (GitHub API)
│   └── update-index.py      # Generate fallback index
├── fallback-index.json      # Static index (API fallback)
└── categories/              # Category-specific guides
    ├── agents.md
    ├── commands.md
    ├── skills.md
    ├── mcps.md
    ├── settings.md
    ├── hooks.md
    └── plugins.md

Agent

Use category-downloader agent to download by category:

Task({
  subagent_type: "general-purpose",
  prompt: `Read .claude/agents/spec2impl/category-downloader.md and execute.
           Category: ${category}
           Requirements: ${requirements}`
})

Categories

| Category | Output Directory | Guide | |----------|-----------------|-------| | agents | .claude/agents/ | categories/agents.md | | commands | .claude/commands/ | categories/commands.md | | skills | .claude/skills/ | categories/skills.md | | mcps | .mcp.json (merge) | categories/mcps.md | | settings | .claude/settings.local.json | categories/settings.md | | hooks | .claude/settings.local.json | categories/hooks.md | | plugins | Multiple locations | categories/plugins.md |

Commands

# List all items in a category
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/download.py list --category agents --json

# Search across categories
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/download.py search "<query>" --json
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/download.py search "<query>" --category skills --json

# Download specific item
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/download.py get "<path>" --output .claude/agents

# View available categories
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/download.py categories

# Clear cache (get fresh data from GitHub)
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/download.py clear-cache

GitHub API Source

• Base URL: https://api.github.com/repos/davila7/claude-code-templates/contents
• Cache: 15 minutes (use --no-cache to bypass)
• Rate Limit: Set GITHUB_TOKEN env var for higher limits (60 req/hour → 5000 req/hour)

Fallback System

GitHub API has rate limits (60 requests/hour without token). When the API fails, the downloader automatically uses a static fallback index.

How It Works

1. Check local cache (15 min TTL)
   ↓ (cache miss)
2. Fetch from GitHub API
   ↓ (rate limit hit / network error)
3. Use fallback-index.json (static backup)

Updating Fallback Index

When new templates are added to the upstream repository, update the fallback index:

# Requires GITHUB_TOKEN for higher rate limits
export GITHUB_TOKEN=your_token_here
python3 .claude/skills/spec2impl/aitmpl-downloader/scripts/update-index.py

This generates fallback-index.json with all available templates.

Rate Limit Status

When rate limited, you'll see:

Using fallback index for agents (API rate limit or network issue)

The fallback ensures the downloader always returns results, even when GitHub API is unavailable.

GitHub Paths

| Category | GitHub Path | |----------|-------------| | agents | cli-tool/components/agents | | commands | cli-tool/components/commands | | skills | cli-tool/components/skills | | mcps | cli-tool/components/mcps | | settings | cli-tool/components/settings | | hooks | cli-tool/components/hooks | | plugins | .claude-plugin |

Output Format (JSON)

[
  {
    "category": "agents",
    "name": "frontend-developer",
    "description": "Agents from development-team",
    "path": "cli-tool/components/agents/development-team/frontend-developer.md",
    "subcategory": "development-team",
    "download_url": "https://raw.githubusercontent.com/..."
  }
]

Workflow

1. Read category guide - Understand available items and mapping
2. List/Search - Find matching templates
3. Download - Get files to local project
4. Verify - Confirm installation