Skip to content

Add INDEX.md grouping skills by category for discoverability #5

@mgiovani

Description

@mgiovani

Problem

With 59 skills in a flat skills/ directory, there is no way to quickly answer the questions a new user naturally asks:

  • "Which skill creates a PR?"
  • "Is there a debugging skill?"
  • "What do all these forge-* skills do?"

The README lists categories but only as a summary paragraph — not as a navigable reference. A flat list of 59 skills is overwhelming to mentees encountering cc-arsenal for the first time.

Proposed solution: INDEX.md

Create an INDEX.md at the repository root that groups every skill by category, with one-line descriptions and links to each skill directory.

Suggested categories (based on actual skills in skills/)

Category Skills
Git & PRs git-commit, git-create-pr, git-release, git-sync, fixpr, merge-pr
Code Quality review-code, review-security, review-deps, review-perf, refactor
Testing test-suite
Implementation implement-feature, fix-bug
Forge (Spec-Driven) forge-architect, forge-brief, forge-dev, forge-qa, forge-review, forge-security, forge-story
Documentation docs-adr, docs-check, docs-diagram, docs-init, docs-rfc, docs-update
Planning project-planner, forge-story, forge-brief
Infrastructure ci-generate, db-migrate, docker-init, env-setup, dokploy-deploy
GitHub / Jira gh-daily, jira-daily, jira-todo, jira-cli, issue, ideas, board
Teams team-implement, team-review
Status & Budgets audit, usage, budget-sweep, scheduler, self-improve
Utilities create-skill, create-command, create-rule, find-skills, agent-browser, nanobanana, md, ask
Orchestration add-project, review, fixpr, merge-pr

Entry format

Each entry in INDEX.md should be:

| [`skill-name`](skills/skill-name/) | One-line description of what it does |

Recommended starter set callout

Include a highlighted callout box (or > [!TIP] block) identifying 5-8 skills ideal for first-time users. Suggested: implement-feature, fix-bug, git-commit, git-create-pr, review-code, docs-init.

Acceptance criteria

  • INDEX.md exists at the repository root
  • Every one of the 59 skills in skills/ is listed and categorized
  • Each entry includes at minimum a skill name (linked to its directory) and a one-line description
  • A "Recommended starter set" section or callout is present for new users
  • README.md links prominently to INDEX.md (e.g. "Browse all 59 skills → INDEX.md")

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions