git:20260909.f4a7570 to git:20260916.0d6e629

# AGENTS.md

This is the canonical, tool-agnostic guidance file for **cc-arsenal**, read natively by Codex, Cursor, Copilot, Gemini CLI, OpenCode, and any other AGENTS.md-aware tool. 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

cc-arsenal is a collection of **54 Agent Skills** ([agentskills.io](https://agentskills.io) open standard) for development workflow automation. `skills/` is the single canonical tier: every skill lives there once, written tool-neutral, and any tool that speaks the Agent Skills format can load it directly.

### Core Components

- **Skills** (`skills/`): 54 skills covering development, code review, documentation, git/GitHub, jira, teams, browser automation, project planning, product specs, multi-agent orchestration, open-source launch prep, and skill discovery/creation/improvement

- **Scripts** (`scripts/`): Python utilities for installation, configuration, and 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, plugin variants, and 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 (`allowed-tools`, `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.

- 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.

## Available Skills (54 total)

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

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

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

- **review-design**: UX/UI/design quality audit mapped to WCAG 2.2 AA, Material Design 3, and Apple HIG

- **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-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

- **gh-daily**: GitHub-based standup report from assigned issues, PRs, and commit history

- **jira-daily**: Smart standup report generator with activity analysis

- **jira-todo**: Smart daily work planner with intelligent prioritization

## 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

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

## File Organization

```

cc-arsenal/

├── skills/ # All 54 skills (canonical, tool-agnostic)

```