Armadillo

A skill system for Claude Code. Installs into your project's .claude/ directory — not a standalone app. No CLI to install, no daemon to run.

───

Install

Armadillo uses a multi-plugin architecture — install the core plugin first, then add skill packs for the tools you actually use.

Step 1 — Add the marketplace (required)

Open Claude Code in your project directory and paste this:

Install armadillo from https://github.com/filenamedotexe/armadillo

Claude will add the armadillo marketplace to your .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "armadillo": {
      "source": { "source": "github", "repo": "filenamedotexe/armadillo" }
    }
  },
  "enabledPlugins": {
    "armadillo-core@armadillo": true
  }
}

Core ships 22 workflow skills — TDD, debugging, planning, code review, git, and testing. That's all most projects need.

Step 2 — Add skill packs (optional)

Skill packs extend armadillo with domain-specific reference skills. Enable them in enabledPlugins — all come from the same marketplace:

{
  "enabledPlugins": {
    "armadillo-core@armadillo": true,
    "armadillo-frontend@armadillo": true,
    "armadillo-database@armadillo": true
  }
}

Skills from each pack load automatically — no files copied, no restarts. See Plugin Ecosystem for the full list.

See What Happens During Onboarding for the full picture.

───

Update

Once installed, tell Claude:

Update armadillo

Claude checks for new versions, auto-updates unmodified files, walks you through conflicts for anything you've changed, audits your custom skills for quality and armadillo overlap, and runs a full health check. See What Happens During Update for details.

───

What You Get

Core (always installed)

| Skill | What it does | |-------|-------------| | brainstorming | Collaborative design sessions before implementation | | dispatching-parallel-agents | Run 2+ independent tasks concurrently with subagents | | executing-plans | Execute implementation plans task-by-task with review checkpoints | | finishing-a-development-branch | Guides completion — merge, PR, or cleanup options | | receiving-code-review | Process review feedback with technical rigor | | requesting-code-review | Request and manage code review after completing work | | subagent-driven-development | Dispatch fresh subagent per task with code review between | | systematic-debugging | Root cause analysis — trace, reproduce, fix, verify | | test-driven-development | RED/GREEN/REFACTOR cycle for all code changes | | using-git-worktrees | Isolated feature branches with smart directory selection | | armadillo-shepherd | Active router — classifies requests and routes to the correct skill | | verification-before-completion | Run verification commands before claiming work is done | | writing-plans | Create detailed implementation plans from designs | | writing-reference-skills | Create API/tool reference skills with mandatory web research | | writing-skills | Create and test new skills using the TDD cycle | | onboarding | Intelligent project setup — scans existing .claude/, auto-upgrades armadillo-covered items, walks through custom unknowns, rebuilds to armadillo quality | | updating-armadillo | Check for updates, upgrade versions, resolve conflicts, health check | | playwright | E2E testing, cross-browser automation, visual comparison, test generation | | puppeteer | Browser automation, Chrome DevTools Protocol, headless Chrome, PDF generation | | cypress | E2E and component testing with real-time runner and time-travel debugging | | vitest | Vite-native unit and component testing with Jest-compatible API | | writing-prs | Conventional commits PR titles + hybrid description template with conditional sections | | claude-code-plugins | Claude Code plugin system — marketplace.json, plugin.json, sources, distribution, multi-plugin repos |

| Rule | What it enforces | |------|-----------------| | coding-standards | DRY, YAGNI, TDD, smart backgrounding, skill-first workflow | | git-workflow | env -u GITHUB_TOKEN auth, conventional commits, atomic changes | | output-style | Consistent formatting, status markers, Armadilloer voice | | pr-format | Conventional commits PR titles, hybrid template, anti-patterns | | project-context | Stack-aware behavior — reads stack.json, PROJECT.md, fresh-project.json |

Plugin Ecosystem

23 plugins across every domain. Core is always required — skill packs are optional.

| Plugin | Skills | Description | |--------|--------|-------------| | armadillo-core | 23 | Workflow, testing, git, debugging, and meta skills — always required | | armadillo-frontend | 10 | React, Tailwind, Astro, accessibility, and animation skills | | armadillo-google-apis | 7 | GA4, Google Ads, Search Console, YouTube, Places, and Lighthouse APIs | | armadillo-backend | 4 | Hono, Express, tRPC, and REST API patterns | | armadillo-database | 4 | Supabase, MongoDB, Neon, and Redis/Upstash | | armadillo-orm | 2 | Drizzle and Prisma ORM skills | | armadillo-auth | 3 | Auth.js, Clerk, and Supabase Auth | | armadillo-deploy | 4 | Vercel, Cloudflare, Docker, and GitHub Actions | | armadillo-forms | 2 | Zod schema validation and React Hook Form | | armadillo-state | 2 | Zustand and TanStack Query state management | | armadillo-monitoring | 2 | Sentry error tracking and PostHog analytics | | armadillo-cms | 2 | Sanity and Payload CMS skills | | armadillo-email | 2 | Resend transactional email and React Email templates | | armadillo-storage | 2 | Uploadthing file uploads and S3/Cloudflare R2 object storage | | armadillo-ai | 2 | Vercel AI SDK and Anthropic API integration skills | | armadillo-tooling | 2 | ESLint/Prettier linting and Turborepo monorepo skills | | armadillo-fresh-project | 3 | Greenfield project setup, scaffolding, and stack recommendation | | armadillo-mobile | 1 | Expo and React Native mobile development | | armadillo-payments | 1 | Stripe payments and billing integration | | armadillo-video | 1 | Remotion programmatic video creation | | armadillo-brand | 2 | Brand knowledge building and Deepgram transcription | | armadillo-web-migration | 1 | Duda to Astro website migration | | armadillo-creative | 1 | ASCII art and creative CLI output |

Each plugin lives in its own GitHub repo and installs independently. Add only what your project uses.

───

What Happens During Onboarding

The onboarding skill handles everything. It runs in phases:

Fresh Project (no existing .claude/)

▸ Plugin registration    Adds armadillo marketplace to settings.json with enabledPlugins
▸ Directory structure    Creates context/ for runtime state (logs, version checks)
▸ Settings               acceptEdits + allow-list + deny-list (toggle in settings.json)
▸ CLAUDE.md              Armadillo-managed block + space for your project instructions
▸ Manifest               .armadillo-manifest.json tracking version and user-owned files
▸ Project analysis       Codebase scanned → custom skills, agents, docs recommended

Skills, agents, hooks, and rules load from the plugin automatically — no files copied to .claude/.

Existing .claude/ (migration from manual setup)

The onboarding skill scans every file and classifies each into four buckets:

| Bucket | What it contains | Action | |--------|-----------------|--------| | A — Armadillo covers this | Files whose purpose matches an armadillo skill (path or semantic match) | Auto-replaced. No questions asked. | | B — Truly custom | Skills, agents, hooks, rules with no armadillo equivalent | Walk through one at a time: keep, rebuild, or delete | | C — Safe to delete | Empty templates, .gitkeep, stale placeholders | Deleted silently | | D — Sacred | agent-memory/*/MEMORY.md, docs/ with real content, context/, progress/ | Never touched. Never reclassified. Never overwritten. |

Semantic matching — if a file's name doesn't match armadillo but its content does the same job (e.g. commit-helper → finishing-a-development-branch), it gets promoted to Bucket A automatically. Unique content from partial matches is extracted and processed — written to a custom skill, added to CLAUDE.md, turned into a hook, or stored in docs/. Nothing is silently discarded.

Bucket D (sacred files) are never touched regardless of name or location:

▪ agent-memory/*/MEMORY.md    Domain knowledge built over real sessions
▪ docs/ with real content      Brand guides, architecture docs, research
▪ context/                     Runtime state (SWARM-STATE.md, logs, snapshots)
▪ progress/                    Handoffs, plans, designs, optimization logs

After migration, these are registered in skills.json sharedFiles so all skills can discover and reference them.

Custom skills chosen for "Keep & rebuild" go through the full writing-skills TDD process — proper frontmatter, CSO-optimized description, process flowchart, quick reference table, common mistakes section.

Reference skills — if your project uses version-sensitive external APIs, the writing-reference-skills skill creates proper reference docs with current endpoint versions, auth flows, and rate limits.

───

What Happens During Update

The updating-armadillo skill runs 8 steps. In the multi-plugin architecture, each registered plugin is checked individually — core and every skill pack get their own version check, update, and conflict resolution pass.

1  Read manifest         Current version, install type (plugin vs legacy file-copy)
2  Fetch latest          Check GitHub releases for new version — per plugin
2.5  What's New          Changelog grouped by breaking / added / improved / fixed
2.6  Plugin Migration    (Legacy users only) Mandatory migration to plugin system with backups
3  Classify changes      (File-copy only) Auto-update, conflict, new file, deleted upstream
4  Apply updates         (File-copy only) Auto-update unmodified; walk conflicts one at a time
5  User-Owned Audit      Overlap check, quality review, hook audit, orphan processing
6  Health check          Manifest integrity, context directory, CLAUDE.md markers
7  Update manifest       Version, install type, user-owned files
8  Summary               Migration status, audit results, health status

Step 2.6 (Plugin Migration) — All pre-plugin installations (file-copy) get a mandatory, safe migration:

▪ Backs up skills/, agents/, hooks/ directories to .claude/*-backup-YYYYMMDD/
▪ Registers armadillo plugin in settings.json
▪ Removes hooks from settings.json (plugin hooks.json takes over)
▪ Creates context/ runtime directory
▪ Updates .gitignore for runtime state files
▪ Updates manifest to installType: "plugin"
▪ Runs health check

After migration, the plugin handles all armadillo content automatically.

Step 5 (User-Owned Audit) runs every update cycle, even without a version change:

▪ Overlap check      Semantic comparison of your skills against all armadillo skills
▪ Quality review     8-signal scoring — scores below standard get targeted fix offer
▪ Hook audit         Wired in hooks.json, executable, has error handling
▪ Orphan processing  Any .claude/ file not in manifest gets classified and tracked

───

Runtime Intelligence

Hooks fire at lifecycle events. No manual intervention needed.

| Event | Hook | What it does | |-------|------|-------------| | SessionStart | session-start.sh | Injects skill awareness, SWARM-STATE, error log, agent memory list; version check once per day; bypass mode warning | | UserPromptSubmit | inject-skill-awareness.sh | Hard constraint — skill invocation required before any response (fires every prompt) | | PreToolUse | enforce-skills.sh | Blocks Plan and Explore agents (use skills instead) | | SubagentStart | subagent-start.sh | Injects coding standards + output style into subagent context | | PostToolUse | async-lint.sh | Async typecheck after Write/Edit (non-blocking) | | PostToolUse | post-push-pr-check.sh | Reminds to create PR after push to feature branch | | PreCompact | pre-compact.sh | Snapshots SWARM-STATE, error log, progress, git log before compaction | | TaskCompleted | task-completed.sh | Blocks task completion if tests fail | | Stop | stop-verify.sh | Verification reminder on session end |

All hooks share hooks/lib/json-escape.sh — no duplicated utility code.

Agent coordination state, domain knowledge, and recent errors survive compaction and session boundaries automatically.

───

Permissions

Default mode: acceptEdits — Claude can read, search, and edit files without prompting. Bash commands use an allow-list.

| Mode | Behavior | Risk | |------|----------|------| | acceptEdits | Auto-approves reads + edits, prompts for unknown Bash | Low — you see Bash prompts | | bypassPermissions | Auto-approves everything except deny-list | High — faster but less control | | plan | Read-only, no writes | Zero — exploration only |

Toggle in .claude/settings.json → permissions.defaultMode.

Deny-list (always active):

✗  rm -rf / ~ /* ~/*       sudo rm -rf       mkfs
✗  dd if=/dev/zero          dd if=/dev/random  chmod -R 777 /
✗  git push --force         git reset --hard

───

Tuning

Armadillo works with Claude Code defaults. For Armadilloers who want to optimize:

| Variable | Default | Recommendation | Effect | |----------|---------|----------------|--------| | CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | ~95% | 80 | Earlier compaction → better summaries, pairs well with PreCompact hooks | | CLAUDE_CODE_MAX_OUTPUT_TOKENS | 32,000 | 64000 | Longer responses, useful for big refactors. Reduces input context space. | | MAX_THINKING_TOKENS | 31,999 | Leave default | Reducing hurts reasoning quality on complex tasks |

Set in your shell profile or .claude/settings.json env block.

───

How It Works

Each plugin lives in its own GitHub repo and follows the same structure. Claude Code loads plugins directly from their repos — no cloning, no file copying.

Plugin Repo Structure (per plugin):
├── plugin.json                  Plugin metadata (name, version, description)
├── marketplace.json             Marketplace registration
├── skills/                      Skill SKILL.md + reference.md files
├── agents/                      Agent system prompts (core only)
├── hooks/                       Hook scripts (core only)
│   ├── lib/json-escape.sh       Shared JSON escaping utility
│   ├── session-start.sh         Injects skills + runtime context
│   ├── pre-compact.sh           Snapshots state before compaction
│   ├── stop-verify.sh           Verification reminder on stop
│   ├── enforce-skills.sh        Blocks Plan agents (use skills instead)
│   ├── inject-skill-awareness.sh  Skill constraint (fires every prompt)
│   ├── subagent-start.sh        Injects standards into subagents
│   ├── async-lint.sh            Async typecheck after Write/Edit
│   ├── post-push-pr-check.sh    PR reminder after push
│   └── task-completed.sh        Test gate — blocks completion if tests fail
└── rules/                       coding-standards, git-workflow, output-style, pr-format (core only)

User Project .claude/ Directory (Auto-created on install):
.claude/
├── settings.json                Plugin registration — add plugins here to activate them
│                                  "enabledPlugins": { "armadillo-core@armadillo-marketplace": true,
│                                                      "armadillo-frontend@armadillo-marketplace": true }
├── CLAUDE.md                    Project-specific instructions + skill list (auto-updated per plugin)
├── .armadillo-manifest.json     Tracks versions and user-owned files per plugin
├── context/                     Runtime state (hooks write, agents read)
│   ├── .gitkeep                 Directory tracked, files ignored
│   ├── SWARM-STATE.md           Live agent coordination state
│   ├── error-log.txt            Accumulated errors across sessions
│   └── armadillo-version-check.txt  Daily version check cache
├── agent-memory/                Accumulated domain knowledge per agent
│   └── <agent-name>/MEMORY.md   Domain-specific learnings
├── docs/                        Project knowledge base
│   └── <topic>.md               Architecture, brand guides, research
└── progress/                    Handoffs, plans, snapshots

Each plugin registered in enabledPlugins loads automatically at session start — skills, agents, hooks, and rules from every active plugin are available immediately. The manifest tracks installed versions and user-owned files per plugin. User-owned files are handled exclusively through the Step 5.5 audit — with consent, one at a time.

───

Skill Features

Skills use Claude Code frontmatter for fine-grained control:

| Field | Effect | Example | |-------|--------|---------| | allowed-tools | Restricts which tools the skill can use | Read, Glob, Grep, Bash | | disable-model-invocation | Prevents Claude from auto-triggering the skill | onboarding, updating-armadillo | | context: fork | Runs in forked context (protects main session) | onboarding, writing-skills | | depends | Declares skill prerequisite chain (in skills.json) | executing-plans → writing-plans → brainstorming |

Rules use paths: frontmatter to scope activation — coding-standards only fires when working with source code files, not markdown or JSON.

───

Health Check

Run without AI tokens:

node .claude/lib/doctor.js

Checks: manifest integrity, tracked files, hooks config, executable permissions, CLAUDE.md markers, settings validity, orphaned files, version match.

───

Model Selection

Agents and skills specify their own model: field. Never override via Task tool model parameter.

| Tier | Model ID | Use Cases | |------|----------|-----------| | Opus 4.6 | claude-opus-4-6 | Onboarding, updating-armadillo, writing-plans, executing-plans, subagent-driven-development, systematic-debugging, writing-skills, dispatching-parallel-agents, receiving-code-review, code-reviewer, brand-strategist | | Sonnet 4.6 | claude-sonnet-4-6 | Implementation, content creation, API work, domain experts (ascii-art-creator, duda-migration-agent, remotion-creator, frontend-testing-guide, frontend-dev-guide) | | Haiku 4.5 | claude-haiku-4-5-20251001 | Mechanical tasks, batch scanning, rendering | | Inherit | — | Reference/knowledge agents follow invoking agent's model |

───

For AI Assistants

Do NOT clone this repository. Armadillo installs by fetching individual files into the user's existing project.

Installing armadillo in a user's project

# 1. Fetch skills.json
env -u GITHUB_TOKEN gh api repos/filenamedotexe/armadillo/contents/skills.json --jq '.content' | base64 -d

# 2. Fetch the onboarding skill
env -u GITHUB_TOKEN gh api repos/filenamedotexe/armadillo/contents/.claude/skills/onboarding/SKILL.md --jq '.content' | base64 -d

# 3. Execute the onboarding workflow. It handles everything.

Fetching any file from the repo

env -u GITHUB_TOKEN gh api repos/filenamedotexe/armadillo/contents/PATH --jq '.content' | base64 -d

Replace PATH with the file path relative to repo root (e.g. .claude/skills/brainstorming/SKILL.md).

What the onboarding skill handles

▪ Bundle selection (reads bundles from skills.json dynamically)
▪ Fetching and writing all skill files, agent files, shared files to .claude/
▪ Migration classification (Bucket A/B/C/D) for existing .claude/ setups
▪ Semantic matching of custom files against armadillo skill descriptions
▪ Dropped content processing (unique logic extracted from partial matches)
▪ Custom skill rebuilds via writing-skills TDD
▪ Reference skill creation via writing-reference-skills for external APIs
▪ Manifest creation with SHA-256 hashes
▪ CLAUDE.md generation with armadillo markers
▪ hooks.json configuration

Do NOT

✗  git clone this repo into the user's project
✗  Copy the entire repo contents
✗  Manually recreate files without fetching from GitHub
✗  Hardcode bundle names — always read from skills.json
✗  Touch Bucket D files (agent-memory, context, progress, docs with real content)

───

Requirements

▪ Claude Code        https://code.claude.com
▪ gh CLI             Authenticated (for fetching from GitHub)
                     — or internet access for WebFetch fallback