agents-init

Initialize agent docs + skills/MCP/subagents in one shot

agents-init is a CLI tool that bootstraps your repository for AI-assisted development. It analyzes your codebase, detects technologies, and automatically configures:

• AGENTS.md - Vendor-neutral guidance for AI coding assistants
• CLAUDE.md - Claude Code configuration that sources AGENTS.md
• .mcp.json - Model Context Protocol server configuration
• Subagents - Specialized AI assistants in .claude/agents/
• Skills - Claude Code skills for your stack
• /agents-init - Slash command to regenerate configuration

If the pace of agent tooling has felt hard to keep up with, you're not alone. "I've never felt this much behind as a programmer." — Andrej Karpathy https://x.com/karpathy/status/2004607146781278521

Quick Start

# One-shot: analyze repo and apply all changes
npx -y agents-init@latest

# Preview what would be generated (no changes)
npx -y agents-init@latest --dry-run

Claude Code Plugin

Install agents-init as a Claude Code plugin for easy access via slash commands.

Installation

# Add the marketplace
/plugin marketplace add Paldom/agents-init

# Install the plugin
/plugin install agents-init

Usage

| Command | Description | |---------|-------------| | /agents-init:analyze | Preview changes (dry-run) | | /agents-init:run | Apply changes | | /agents-init:help | Show usage and examples |

Note: Plugin commands are namespaced as /agents-init:... (colon separator).

Alternative: Direct CLI

You can also run agents-init directly without the plugin:

npx -y agents-init@latest --dry-run  # Preview
npx -y agents-init@latest            # Apply

Features

Tag-Based Selection

The tool uses a comprehensive tag taxonomy to match your project with relevant:

• Skills - Claude Code skills packages
• MCP Servers - External tool integrations
• Subagents - Specialized AI assistants

All selections use the same tag overlap scoring algorithm, ensuring consistency.

Intelligent Detection

Automatically detects:

• Languages (TypeScript, Python, Go, Rust, etc.)
• Frameworks (Next.js, React, Vue, Django, FastAPI, etc.)
• Databases (PostgreSQL, MongoDB, Redis, Prisma, Drizzle, etc.)
• Platforms (Vercel, Cloudflare, AWS, etc.)
• Testing frameworks (Jest, Vitest, Playwright, Cypress, etc.)
• CI/CD pipelines (GitHub Actions, GitLab CI, etc.)

CLI Usage

agents-init [root] [options]

Options

| Flag | Description | |------|-------------| | --dry-run | Preview changes without writing anything | | --no-interactive | Non-interactive mode (for CI/CD) | | --no-claude | Skip Claude-powered generation, use templates only | | --no-agents-md | Skip AGENTS.md generation | | --no-skills | Skip skills installation | | --no-mcp | Skip MCP configuration | | --no-subagents | Skip subagent installation | | --force | Overwrite existing files (backups created by default) | | --catalog <path> | Path to custom catalog file | | --telemetry | Allow skills CLI telemetry (off by default) | | -v, --verbose | Verbose logging |

Examples

# One-shot: analyze and apply all changes
npx -y agents-init@latest

# Preview changes (dry run)
npx -y agents-init@latest --dry-run

# CI/CD friendly (non-interactive)
npx -y agents-init@latest --no-interactive

# Only generate docs, skip skills and MCP
npx -y agents-init@latest --no-skills --no-mcp

# Use deterministic templates (no Claude CLI needed)
npx -y agents-init@latest --no-claude

# Verbose output
npx -y agents-init@latest --verbose

Programmatic API

import { agentsInit } from 'agents-init';

// One-shot: analyze and apply
const result = await agentsInit({
  root: '/path/to/repo',
  maxSkills: 5,
  maxMcp: 5,
  maxSubagents: 8,
});

console.log(result.tags);       // Detected tags
console.log(result.selections); // Selected skills, MCP, subagents
console.log(result.files);      // Generated file paths

// Preview only (no changes)
const preview = await agentsInit({
  root: '/path/to/repo',
  dryRun: true,
});

Analysis Only

import { analyzeRepository } from 'agents-init';

const { profile, tags, selections, explanation } = await analyzeRepository(
  '/path/to/repo'
);

console.log(explanation); // Human-readable selection summary

What Gets Created

AGENTS.md

A comprehensive guide for AI assistants including:

• Project overview and tech stack
• Directory structure
• Development guidelines
• Testing information
• Common commands
• Environment variables
• MCP server notes

CLAUDE.md

A minimal file that sources AGENTS.md:

@AGENTS.md

.mcp.json

MCP server configuration with environment variable placeholders:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

.claude/commands/agents-init.md

A slash command to regenerate configuration:

/agents-init

Note: For backwards compatibility, .claude/commands/scaffold.md is also generated as a deprecated alias that forwards to /agents-init.

.claude/agents/*.md

Specialized subagents for your stack, e.g.:

• frontend-developer.md
• backend-developer.md
• database-expert.md
• qa-engineer.md

Tag Taxonomy

The tool uses a comprehensive tag taxonomy covering:

• Languages: JavaScript, TypeScript, Python, Go, Rust, Java, etc.
• Frontend: React, Next.js, Vue, Nuxt, Svelte, Angular, etc.
• Backend: Express, Fastify, NestJS, Django, FastAPI, etc.
• Databases: PostgreSQL, MySQL, MongoDB, Redis, Prisma, Drizzle, etc.
• Platforms: Vercel, Cloudflare, AWS, GCP, Azure, etc.
• DevOps: Docker, Kubernetes, Terraform, GitHub Actions, etc.
• Testing: Jest, Vitest, Playwright, Cypress, etc.
• Roles: Frontend Developer, Backend Developer, DevOps Engineer, etc.

See src/tags.ts for the complete list.

Skills & MCP

Skills (from skills.sh)

agents-init recommends Skills based on tags and can optionally install them.

npx skills add sickn33/antigravity-awesome-skills --skill "typescript-expert"

The catalog includes 201 skills from antigravity-awesome-skills:

| Category | Count | |-----------------------------|-------| | Architecture & Full-Stack | 9 | | Backend Development | 8 | | Frontend Development | 7 | | React & Next.js | 6 | | TypeScript & JavaScript | 3 | | UI / Design Systems | 10 | | Database & Data | 5 | | Authentication & BaaS | 3 | | Testing & QA | 9 | | Code Quality & Standards | 5 | | DevOps & Infrastructure | 13 | | Git & Version Control | 4 | | Security & Compliance | 32 | | AI / LLM / Agents | 32 | | RAG & LLM Frameworks | 5 | | Voice & Realtime AI | 3 | | API Design & Integration | 5 | | E-commerce & Payments | 5 | | Documentation & Planning | 15 | | Marketing & Growth | 20 | | CRO & User Experience | 8 | | Email & Communications | 5 | | Bots & Realtime | 6 | | CRM & Business Integrations | 3 | | Performance & Optimization | 2 | | Game Development | 1 | | i18n / Localization | 1 |

Docs: skills.sh/docs

MCP Servers (from the MCP Registry)

agents-init recommends MCP servers from the official registry and writes them into .mcp.json with env var placeholders for secrets.

| Category | Servers | |----------|---------| | Cloud Platforms | azure, digitalocean, fly, render, railway, heroku, netlify | | Web/Search | brave-search, fetch, firecrawl | | Design | figma | | Communication | gmail, google-calendar, jira | | Version Control | git | | Observability | grafana, prometheus, opentelemetry, newrelic | | Documentation | context7, markitdown | | DevOps/IaC | ansible, pulumi, circleci, github-actions, gitlab-ci | | AI/LLM | anthropic, langchain, llamaindex, chromadb | | Databases | dynamodb, cassandra, convex, appwrite, xata | | ORMs | prisma, drizzle, sequelize, typeorm, knex, kysely, sqlalchemy | | Testing | cypress, jest, vitest, pytest, selenium, testing-library, msw | | Auth | nextauth, lucia, better-auth, passport | | CMS | strapi, payload, keystonejs | | E-commerce | shopify, medusa | | Real-time | kafka, rabbitmq, nats, pusher, socket-io | | API Protocols | graphql, grpc, trpc, openapi | | Docs Tools | docusaurus, nextra, vitepress |

• Registry: registry.modelcontextprotocol.io
• Claude Code MCP docs: code.claude.com/docs/en/mcp

Subagents (from VoltAgent)

Subagents are sourced from VoltAgent's collection.

The catalog includes 115 subagents across 10 plugins:

| Plugin | Count | |--------------------|-------| | voltagent-core-dev | 11 | | voltagent-lang | 26 | | voltagent-infra | 14 | | voltagent-qa-sec | 14 | | voltagent-data-ai | 12 | | voltagent-dev-exp | 13 | | voltagent-domains | 12 | | voltagent-biz | 10 | | voltagent-meta | 11 | | voltagent-research | 6 |

Requirements

• Node.js 18+ (LTS versions recommended)
• Git (for repository analysis)
• Claude Code CLI (optional, for enhanced generation)

Compatibility

| Platform | Status | |----------|--------| | Linux | ✅ Fully supported | | macOS | ✅ Fully supported | | Windows | ✅ Fully supported |

Security & Privacy

What Files Are Read

• package.json, tsconfig.json, and other config files
• Source files (by extension) for language detection
• .gitignore for respecting ignored files

What Files Are Never Read

The tool automatically excludes files that may contain secrets:

• .env, .env.*, .envrc
• *.pem, *.key, id_rsa, SSH keys
• credentials.json, service-account*.json
• *.tfstate, *.tfvars (Terraform state)
• secrets.yaml, vault.yaml
• Database files (*.sqlite, *.db)

Supply Chain Security

• All GitHub Actions pinned to full commit SHAs
• npm packages published with provenance attestations
• OpenSSF Scorecard monitoring enabled
• Minimal runtime dependencies (9 total)

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli.js --dry-run

# Type check
npm run typecheck

# Run tests
npm test

# Lint
npm run lint

# Validate catalogs
npm run catalog:lint

Release Process

This project uses Changesets for versioning and publishing.

For Contributors

When making a change that should be released:

npm run changeset

This creates a changeset file describing your change. Commit it with your PR.

Automated Releases

1. Changesets accumulate on main
2. A "Release" PR is automatically created/updated
3. Merging the Release PR triggers:
   • Version bump in package.json
   • CHANGELOG.md update
   • npm publish with provenance
   • GitHub release creation

Publishing Security

• Uses npm Trusted Publishing (OIDC) - no long-lived tokens
• Provenance attestations link packages to source commits
• All builds are reproducible from source

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Links

• AGENTS.md Standard
• Claude Code Documentation
• MCP Registry
• Skills CLI
• VoltAgent Subagents