# Skills Mapping

## Purpose

Map Claude Code skills to project domains and provide guidance on when to use each skill.

## Scope

**In**: Skill selection guidance, domain mapping, best practices.
**Out**: Skill implementation details (see skill documentation).

## Do

- Use skills when appropriate
- Follow skill-specific guidelines
- Invoke skills before starting work when applicable

## Do Not

- Skip skills for tasks they're designed for
- Use wrong skill for the task
- Rationalize not using applicable skills

> This map references **only skills shipped under `framework/.claude/skills/`**.
> Confirm a skill exists (its directory is present) before routing to it; never
> route to a skill name that has no directory.

## Core Development Skills

### prd

**When to use**:

- Starting a new feature (scoping + planning)
- Unclear or multi-part requirements
- Multiple possible approaches / design decisions needed
- Need a PRD + UI design + atomic backlog cards before implementation

**Triggers**:

- "Plan [feature]"
- "Crea un PRD"
- "Nuova funzionalità"
- "How should I scope..."

### context-primer

**When to use**:

- Before starting work on an unfamiliar area of the codebase
- Need existing patterns/architecture loaded silently into context

**Triggers**:

- "/cont [keywords]"
- Auto-invoked by `/prd` at kickoff

### new

**When to use**:

- Implementing one or more approved backlog cards end-to-end
- Multi-step implementation across a worktree with review/QA/commit per card

**Triggers**:

- "/new CARD-IDS"
- "Implementa le card"
- "Esegui le card"

### bug

**When to use**:

- Bug investigation
- Test failures / unexpected behavior
- Regression hunting

**Triggers**:

- "/bug"
- "Fix [bug]"
- "Non funziona" / "Why is [X] not working?"

## Code Quality Skills

### simplify

**When to use**:

- Reducing complexity in a changed area (reuse, dedup, altitude cleanups)
- After major implementation, before commit

**Triggers**:

- "/simplify"
- "Semplifica"
- "Reduce duplication"

> Code review and pre-merge gates are run by the `/new` orchestration
> (`code-reviewer` agent + `qa-sentinel` gate run) and the `/codexreview`
> command — not by a standalone "code-review" skill. Route review tasks there.

## UI/UX Skills

### frontend-design

**When to use**:

- Building UI components
- Creating pages
- Styling work

**Triggers**:

- "Create [page]"
- "Build [component]"
- "Design [interface]"

### ui-design

**When to use**:

- Designing new pages or components (context-aware mockups)
- The `/prd` skill reaches its UI design phase
- Redesigning existing pages / creating design options for review

**Triggers**:

- "/ui-design"
- "Design UI" / "mockup" / "opzioni di design"
- Design-heavy features, visual refinement, design-system work

> `ui-ux-pro-max` is a **tool used inside** the `ui-expert` agent / `ui-design`
> skill (see REGISTRY.md — listed as a Key Tool of `ui-expert`), not a
> standalone invocable BALDART skill. Route UI work through `ui-design` /
> `ui-expert`, not to `ui-ux-pro-max` directly.

## Testing Skills

### playwright-skill

**When to use**:

- Browser automation
- E2E testing
- UI testing

**Triggers**:

- "Test [page]"
- "Automate [flow]"
- Visual regression testing

### webapp-testing

**When to use**:

- Full webapp testing
- Server lifecycle management
- Comprehensive test orchestration

**Triggers**:

- Full application testing
- Integration testing
- Server management needed

## Documentation Skills

### doc-writing-for-rag

**When to use**:

- Writing/rewriting dense reference documentation optimized for RAG indexing
- Creating endpoint/reference docs in `${paths.references_dir}`

**Triggers**:

- "doc per RAG" / "dense documentation"
- "template endpoint" / "compattare docs"

### copywriting

**When to use**:

- User-facing content, marketing copy, microcopy
- Tone/voice refinement

**Triggers**:

- "Scrivi la copy"
- "Migliora il testo"
- Landing/marketing content

## Project-Specific Skills

Add your project-specific skills here:

### [Your Skill 1]

**When to use**: [Description]
**Triggers**: [When to invoke]

### [Your Skill 2]

**When to use**: [Description]
**Triggers**: [When to invoke]

## Skill Selection Decision Tree

```
START: User gives a task
  |
  v
Is it a new feature needing scope/plan?
  |-- YES --> /prd (scopes + plans + writes cards)
  |           Then /new (implements the cards end-to-end)
  |
  v
Is it a bug fix?
  |-- YES --> /bug (5-phase investigation + fix)
  |
  v
Is it UI/visual work?
  |-- YES --> /ui-design (mockups/options) or frontend-design
  |
  v
Is it browser testing?
  |-- YES --> playwright-skill or webapp-testing (E2E via /e2e-review)
  |
  v
Is it cleanup/complexity reduction?
  |-- YES --> /simplify
  |
  v
Proceed with appropriate skill
```

## Skill Chaining

Common skill chains (all skills below are shipped under `.claude/skills/`):

1. **New Feature**:
   - /prd → /new (the orchestrator runs `code-reviewer` + `qa-sentinel` gates per card)

2. **Bug Fix**:
   - /bug → (fix lands through the bug skill's verify phase)

3. **UI Feature**:
   - /prd → /ui-design → /new → playwright-skill (or /e2e-review for blocking E2E)

4. **Refactoring**:
   - /simplify (identify + apply cleanups) → /new gates re-run lint/tsc/tests

## Anti-Patterns

**Don't**:

- Skip `/prd` scoping for "simple" multi-part features
- Start coding before planning
- Skip the per-card `qa-sentinel` gate run because "I know how to fix it"
- Claim completion before the `/new` review + gate cycle passes
- Use wrong skill for the task
- Route to a skill name that has no directory under `.claude/skills/`

**Do**:

- Follow skill workflows
- Chain skills appropriately
- Use skills even when they seem "overkill"
- Trust the skill process

## Skill Configuration

Some skills may require configuration:

- [Skill-specific config location]
- [Environment variables needed]
- [Setup requirements]

## Custom Skills

Document how to create custom skills:

1. Create skill file in `.claude/skills/`
2. Follow skill template format
3. Document when to use
4. Add to this mapping file
