Initialize agent docs + tag-driven skills/MCP/subagents in one shot
npm install 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
---
``bashOne-shot: analyze repo and apply all changes
npx -y agents-init@latest
---
Claude Code Plugin
Install agents-init as a Claude Code plugin for easy access via slash commands.
$3
bash
Add the marketplace
/plugin marketplace add Paldom/agents-initInstall the plugin
/plugin install agents-init
`$3
| Command | Description |
|---------|-------------|
|
| 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).$3
You can also run agents-init directly without the plugin:
`bash
npx -y agents-init@latest --dry-run # Preview
npx -y agents-init@latest # Apply
`---
Features
$3
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.
$3
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
bash
agents-init [root] [options]
`$3
| Flag | Description |
|------|-------------|
|
| 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 to custom catalog file |
| --telemetry | Allow skills CLI telemetry (off by default) |
| -v, --verbose | Verbose logging |$3
`bash
One-shot: analyze and apply all changes
npx -y agents-init@latestPreview changes (dry run)
npx -y agents-init@latest --dry-runCI/CD friendly (non-interactive)
npx -y agents-init@latest --no-interactiveOnly generate docs, skip skills and MCP
npx -y agents-init@latest --no-skills --no-mcpUse deterministic templates (no Claude CLI needed)
npx -y agents-init@latest --no-claudeVerbose output
npx -y agents-init@latest --verbose
`---
Programmatic API
typescript
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,
});
`$3
typescript
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
$3
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
$3
A minimal file that sources AGENTS.md:
md
@AGENTS.md
`$3
MCP server configuration with environment variable placeholders:
json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
`$3
A slash command to regenerate configuration:
/agents-init
> Note: For backwards compatibility,
is also generated as a deprecated alias that forwards to /agents-init.$3
Specialized subagents for your stack, e.g.:
-
frontend-developer.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
$3
recommends Skills based on tags and can optionally install them.`bash
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
$3
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
$3
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)
$3
| Platform | Status |
|----------|--------|
| Linux | ✅ Fully supported |
| macOS | ✅ Fully supported |
| Windows | ✅ Fully supported |
---
Security & Privacy
$3
-
package.json, tsconfig.json, and other config files
- Source files (by extension) for language detection
- .gitignore for respecting ignored files$3
The tool automatically excludes files that may contain secrets:
-
.env, .env.*, .envrc
- , .key, id_rsa, SSH keys
- credentials.json, service-account*.json
- , .tfvars (Terraform state)
- secrets.yaml, vault.yaml
- Database files (, .db)$3
- All GitHub Actions pinned to full commit SHAs
- npm packages published with provenance attestations
- OpenSSF Scorecard monitoring enabled
- Minimal runtime dependencies (9 total)
---
Development
`bash
Install dependencies
npm installBuild
npm run buildRun locally
node dist/cli.js --dry-runType check
npm run typecheckRun tests
npm testLint
npm run lintValidate catalogs
npm run catalog:lint
`---
Release Process
This project uses Changesets for versioning and publishing.
$3
When making a change that should be released:
bash
npm run changeset
`This creates a changeset file describing your change. Commit it with your PR.
$3
1. Changesets accumulate on
2. A "Release" PR is automatically created/updated
3. Merging the Release PR triggers:
- Version bump in
- - Uses npm Trusted Publishing (OIDC) - no long-lived tokens
- Provenance attestations link packages to source commits
- All builds are reproducible from source
---
See CONTRIBUTING.md for development setup and guidelines.
---
MIT
---
- AGENTS.md Standard
- Claude Code Documentation
- MCP Registry
- Skills CLI
- VoltAgent Subagents