git:20261005.b620662 to git:20261005.b0bf138

# AGENTS.md

This is the canonical, tool-agnostic guidance file for **cc-arsenal**. Any AGENTS.md-aware tool reads it natively, including Codex, Cursor, Copilot, Gemini CLI and OpenCode. Claude Code does not read this file directly; `CLAUDE.md` imports it via `@AGENTS.md` and adds Claude-Code-only content on top.

## Repository Architecture

### Core Components

- **Scripts** (`scripts/`): Python utilities for installation and configuration, plus code generation (Claude-Code-specific; see `CLAUDE.md`)

- **Integrations** (`integrations/`): agent-CLI-specific tooling that doesn't fit the tool-agnostic `skills/` tier, one subdirectory per agent CLI. Today that's `integrations/claude-code/`, holding the statusline and the `claude-hi` session scheduler; future agent CLIs (Codex, Gemini CLI, ...) get sibling directories alongside it as their own tooling needs arise.

## Install in any agent

```bash

# Any Agent-Skills-compatible tool (Codex, Cursor, Gemini CLI, OpenCode, ...)

npx skills add mgiovani/cc-arsenal

```

`npx skills` is the [skills.sh](https://skills.sh) CLI: it copies each skill into the target tool's own skills directory, no plugin system required.

Using Claude Code? See `CLAUDE.md` for the plugin marketplace install and plugin variants, plus other Claude-Code-only extras.

## Portability convention

Skills in this repo are written **tool-neutral first**:

- Only `name` and `description` frontmatter are required for a skill to work anywhere.

- Claude-Code-only frontmatter keys (`disable-model-invocation`, `hooks`, `context`, `agent`) are enhancement layers. Other tools ignore unknown frontmatter keys safely: a skill's correctness must never depend on them being honored.

- No skill declares `allowed-tools`: in Claude Code it only pre-approves tools for the turn that invokes the skill and restricts nothing, so it adds a permission grant users must vet without making anything safer. Users who want fewer prompts add allow rules to their own settings.

- Orchestration skills (those that spawn subagents/parallel tasks in Claude Code) degrade gracefully to sequential inline execution when no subagent/task tool exists. The instructions describe the sequential fallback explicitly rather than assuming Task/Agent tools are always present.

- Paths and shell commands referenced inside a skill must be real, tool-independent commands (e.g. `git`, `gh`, `make`): never a Claude-Code-only tool name used as if it were a shell command.

## Skill composition

Skills may build on each other along two distinct axes, keep them separate:

- **Sibling invocation (borrow a *procedure*)**: a skill may invoke another skill by name to reuse its steps, via the Claude Code `Skill` tool where available. Because `Skill` is Claude-Code-only and other CLIs can only read a sibling's `SKILL.md` as text, **every such call must state the tool-neutral fallback in the same sentence**: apply the sibling's documented rules/steps inline. Announce it with a `Using <skill> to <purpose>` line. For example: "use the `git-commit` skill to write the message (via the `Skill` tool where available, otherwise apply its conventional-commit rules inline)".

- **Subagent delegation (spawn a *role*)**: a skill may fan work out to a subagent via the Claude Code `Task`/`Agent` tools. This is the orchestration path the Portability convention already covers, and it degrades to sequential inline execution when no subagent tool exists.

Do not add `uses:`/`composes:` frontmatter and do not route composition through a mandatory dispatcher skill: plain prose naming the sibling, with its in-sentence fallback, is the whole mechanism.

<!-- gen:skills-agents start -->

<!-- generated: edit skills.sh.json or SKILL.md frontmatter, then run `make docs` -->

All skills use progressive disclosure (SKILL.md + optional references/scripts/assets directories).

### AI Workflow Tools (9 skills)

Tools that work on your AI agent itself, not on your codebase.

- `agent-browser`: AI-optimized browser automation with far less context overhead than raw Playwright/DOM tools

- `anything-to-skill`: Turn docs sites, PDFs, folders, YouTube videos or a topic into a grounded, token-efficient agent skill

- `create-rule`: Create CLAUDE.md/AGENTS.md rules and memory guidelines

- `create-skill`: Specification-driven skill creation with eval system and description optimization

- `find-skills`: Discover and install third-party agent skills from skills.sh

- `improve-skill`: Rewrite an existing skill to the authoring standard, with baseline-vs-new eval evidence

- `optimize-ai-setup`: Measure token waste across installed AI coding tools and rank the fixes

- `render`: Turn any output into an interactive HTML page you mark up in place, then read the marks back

- `wtf`: Re-explain your own previous message in plain, simplified English (ASD-STE100 style) when the user didn't understand it

### Art & Images (3 skills)

Mascots and logos, hero images and social cards, plus motion videos rendered from code.

- `codex-imagegen`: Polished raster art (logos, mascots, heroes, sprites, mockups) via Codex CLI's $imagegen

- `motion-studio`: Motion videos rendered from code: seek(t) engine, springs, beat-synced sound, critique loop, styles, HyperFrames and Remotion

- `project-illustrator`: A cohesive art system for a project: mascot, heroes, social cards and thumbnails with one character

### Build (5 skills)

Feature work and bug fixes, plus refactors and test coverage for code you already have.

- `clotho-research`: Find what a change will actually touch before planning it: the code and prior art it meets, and the risks it carries

- `fix-bug`: Test-driven debugging with strict sequential task chain and dependency enforcement

- `implement-feature`: Feature implementation with senior staff engineer best practices and parallel subagent orchestration where available

- `refactor`: Restructure existing code without changing behavior, verified against the full test suite at each step

- `test-suite`: Generate test suites by analyzing coverage gaps and writing tests that match project conventions

### Design (3 skills)

Screens and flows, alongside design tokens and an accessibility-grade UX audit.

- `product-design-spec`: Information architecture, user flows, screen inventory and per-screen states for an approved PRD

- `product-design-tokens`: A durable W3C DTCG design-token contract, reusing your design system and enforcing WCAG 2.2 AA contrast

- `review-design`: UX/UI/design quality audit mapped to WCAG 2.2 AA plus the Material Design 3 and Apple HIG guidelines

### Docs (6 skills)

Architecture records and RFCs, plus diagrams and keeping docs honest about the code.

- `docs-adr`: Architecture Decision Records creation and management

- `docs-check`: Documentation validation and health scoring

- `docs-diagram`: Architecture diagrams generation (Mermaid)

- `docs-init`: Documentation structure initialization

- `docs-rfc`: Request for Comments documentation

- `docs-update`: Documentation sync with codebase state

### Git (4 skills)

Branching and committing, plus merging and tagging versions in your own repository.

- `git-commit`: Conventional commit message generation

- `git-release`: Semantic version releases with automated changelog generation

- `git-sync`: Sync the current feature branch with its base/upstream via merge or rebase

- `gitflow`: Manage a gitflow branching workflow (feature/release/hotfix branches)

### GitHub (3 skills)

Pull requests and merges, then taking a project public.

- `git-create-pr`: Pull request creation with standardized formats

- `oss-launch`: Take a private project public: secrets and license pre-flight, branding, README rewrite, then flip it

- `ship`: Orchestrates a branch from "code done" to "merged" (runs review-code plus project-specific pre-merge checks)

### Jira (1 skill)

Jira from the command line.

- `jira-cli`: Interactive command-line tool for Atlassian Jira

### Multi-agent (1 skill)

Fan a large task out across parallel agents.

- `orchestrate`: Decompose a task, map each part to the right model, run independent tracks in parallel, then synthesize

### Product (3 skills)

Decide what to build and turn it into tracked, dependency-ordered work.

- `prd-to-issues`: Turn an approved PRD into tracked issues, one per requirement ID, with dependencies recorded

- `product-prd`: Right-sized PRD from an idea: brief, one-pager, PR/FAQ or full doc, with non-goals and testable requirements

- `project-planner`: Break down large projects into dependency-aware tasks with Mermaid visualization

### Project setup (6 skills)

Containers and environment variables, database migrations and CI pipelines, as well as framework docs.

- `ci-generate`: Generate a production-ready CI/CD pipeline config (GitHub Actions, GitLab CI, CircleCI, Jenkins)

- `ci-local`: Run the checks a GitHub Actions workflow would run, locally, when Actions is unavailable

- `db-migrate`: Create and validate database migrations, then manage them across any framework

- `docker-init`: Generate Dockerfiles and docker-compose.yml with auto-detected services and security hardening

- `env-setup`: Scan a codebase for env var usage, sync .env.example, and detect leaked secrets

- `inject-docs`: Inject compressed framework-specific best practices and docs into CLAUDE.md/AGENTS.md

Code and plans, security and dependencies, performance and visual regressions, and translations.

- `i18n-check`: i18n completeness checker, detects the project's i18n framework and diffs locale files

- `review-code`: Adaptive multi-agent code review: core dimensions plus architecture, security, deps, perf and design lanes picked from the diff, with adversarial verification

- `review-deps`: Audit dependencies for vulnerabilities, license risk, and staleness

- `review-perf`: Deep-dive performance audit of queries, algorithmic complexity, and resource leaks

- `review-plan`: Adversarially review an implementation plan against the actual repository before any code is written

- `review-security`: OWASP Top 10 2025 security analysis with parallel scanning agents where available

- `vrt-check`: Runs the project's visual regression testing workflow, whatever tooling the repo actually uses

<!-- gen:skills-agents end -->

## Skill Anatomy

Skills are modular capabilities organized with this structure:

```

skill-name/

├── SKILL.md (required)

│ ├── YAML frontmatter (name, description, + optional tool-enhancement keys)

│ └── Markdown instructions

├── evals/ (optional but recommended)

│ ├── evals.json - task-completion evals: prompt + assertions per scenario

│ └── trigger-eval.json - description-triggering evals: does the skill fire on the right prompts?

└── Bundled Resources (optional)

├── scripts/ - Executable code (Python/Bash/etc.)

├── references/ - Documentation loaded as needed

└── assets/ - Files used in output (templates, etc.)

```

### Progressive Disclosure

Skills use a three-level loading system:

1. **Metadata** (name + description): always in context (~100 words)

2. **SKILL.md body**: loaded when the skill activates (<5k words)

3. **Bundled resources**: loaded only when the agent needs them

### Eval Convention

Each skill's `evals/evals.json` lists concrete scenarios (`id`, `prompt`, `assertions`) that a run of the skill must satisfy, used to catch regressions when a SKILL.md is edited. `evals/trigger-eval.json` instead tests description-triggering: given a set of realistic user prompts, does the skill's frontmatter `description` cause it to fire (or correctly not fire)? Use the `create-skill` skill's eval tooling to run either against a live agent.

## Development Commands

```bash

# Development Environment

make dev # Set up development with all dependencies

make pre-commit-install # Install pre-commit hooks

make pre-commit-run # Run pre-commit on all files

# Code Quality

make check # Run all checks (lint + type-check)

make lint # Run ruff linting

make format # Format code with ruff

make type-check # Run pyright type checking

# Testing

make test # Run unit tests

make coverage # Tests with coverage report

# Utilities

make clean # Clean caches and build artifacts

make info # Show repository statistics

make validate-structure # Validate repository structure

make validate-plugins # Validate plugin manifests

```

Claude-Code-specific install/config commands (`make install`, `make dry-run`, `make configure`, statusline, claude-hi) live in `CLAUDE.md`.

## Contributing

1. **Fork** the repository and create a feature branch

2. **Develop** your skill or change: new skills go under `skills/<name>/SKILL.md`; keep frontmatter to `name` + `description` plus a one-line `metadata.summary` (what the generated catalogs show), unless the skill genuinely needs a Claude-Code-only key (see Portability convention above)

3. **Assign it a group** in `skills.sh.json`, the single source of truth for how skills are grouped on skills.sh and in every catalog in this repo. `make docs` then regenerates the lists in `README.md`, `AGENTS.md` and `docs/features.md`; `make check` fails if you forget. Every skill must belong to exactly one group

4. **Add evals**: new or changed skills should ship an `evals/evals.json` (and `trigger-eval.json` if the description changed)

5. **Validate** with `make check` and `make validate-structure` / `make validate-plugins`

6. **Update CHANGELOG.md** for user-facing changes

7. **Submit** a pull request with a clear description

See `CONTRIBUTING.md` for the full development setup.

## File Organization

```

cc-arsenal/

│ └── <name>/ # SKILL.md + optional references/, scripts/, assets/, evals/

├── scripts/ # Installation and utilities (see CLAUDE.md for Claude-Code-specific ones)

└── integrations/ # Agent-CLI-specific tooling, one subdirectory per agent CLI

└── claude-code/ # Statusline and the claude-hi session scheduler

```