refactor: consolidate and clarify skills

- Remove redhat-writing skill (user-specific, not generic workspace)
- Merge python-conventions + data-pipeline-patterns → python-patterns (unified team patterns for Python development: credentials, APIs, testing, pipelines)
- Clarify brainstorming skill: explicit activation triggers ("design", "how should i build", "plan this out")
- Clarify cost-speed-meter skill: explicit use cases ("which is slowest?", "measure before/after optimization")
- Add skill dependencies to ai-workspace.toml with explicit mapping of which commands require which skills
- Document architecture in SKILLS_ARCHITECTURE.md (always-loaded skills, activation model, dependencies, design rationale)

Consolidation reduces cognitive load: one unified python-patterns skill vs three separate convention skills. Clarity improvements let users understand when/how to use each skill. Dependency mapping catches future conflicts earlier.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: Benkapner

SKILLS_ARCHITECTURE.md

@@ -0,0 +1,97 @@
+# Skills Architecture
+
+This document maps all skills, their purpose, activation triggers, and relationships.
+
+## Skills Overview
+
+### Core Verification & Review (always available)
+
+**`verification-loop`** — Unified verification engine covering 7 phases: environment check, type check, lint, tests, code review, security scan, pre-push checks. Invoked by `/verify`, `/quality-gate`, and code-review commands. Core skill powering the entire QA workflow.
+
+**`refactoring-patterns`** — Measurement-driven refactoring (profile → refactor → measure). Activates when user says "refactor", "clean up", "simplify", or when code has high complexity. Ensures changes improve metrics, not just code appearance.
+
+**`update-docs`** — Detects stale documentation after code changes by matching diff against in-repo docs. Finds and updates prose that contradicts new code. Auto-activates when implementing features/fixes that rename, remove, or add APIs.
+
+**`security-check`** — Scans for credential leaks, secrets in code, insecure patterns, LLM API key exposure, PII leakage to external services, and `.env/.gitignore` misconfigurations. Runs automatically before commits and when editing credential-related code.
+
+### Python Development (language-specific)
+
+**`python-patterns`** — Unified conventions for team Python development:
+- **Credentials:** dotenv loading, fail-fast on missing secrets, `.env.example` patterns
+- **API clients:** timeouts (30s), transient retry logic, response validation, LLM response parsing
+- **Testing:** TDD workflow, mock external APIs, set `random_state=42`, 80%+ coverage
+- **Pipelines:** standard stage structure, JSON metadata, validation-before-processing, fail-fast, checkpointing
+
+Replaces separate `python-conventions` and `data-pipeline-patterns` skills (merged for clarity).
+
+### Design & Workflow
+
+**`brainstorming`** — Design exploration before implementation. Activates when user asks "design", "how should i build", "what's the approach", "plan this out". Proposes 2-3 approaches with trade-offs, gets approval before coding.
+
+**`cost-speed-meter`** — Tracks command execution times (tests, builds, lint) across sessions. Shows trends, detects regressions, suggests fast-path alternatives (unit tests vs integration). Measures if optimizations actually worked.
+
+## Skill Activation Model
+
+| Skill | Activation Type | Trigger |
+|-------|-----------------|---------|
+| `verification-loop` | Command-invoked | `/verify`, `/quality-gate`, code-review commands |
+| `refactoring-patterns` | Declarative | User says "refactor", "simplify", "clean up", or high complexity detected |
+| `update-docs` | Declarative | Code changes APIs/configs/CLI flags; user asks "update docs" |
+| `security-check` | Declarative | Editing credential/secret handling code; before commits |
+| `python-patterns` | Declarative | Editing Python code files (any `.py` file in context) |
+| `brainstorming` | Declarative | User explicitly asks for design, planning, or approach exploration |
+| `cost-speed-meter` | Automatic | Tracks all bash command execution; invoked via `/metrics` or `/metrics-report` |
+
+## Command Dependencies
+
+Commands that rely on specific skills:
+
+| Command | Requires | Notes |
+|---------|----------|-------|
+| `/verify` | `verification-loop` | Runs phases 1-4: environment, types, lint, tests |
+| `/quality-gate` | `verification-loop` | Runs phases 1-4 + phase 6: plus pre-push security |
+| `/refactor-safe` | `verification-loop`, `refactoring-patterns` | Verify code works before refactoring, then measure |
+| `/test-coverage` | `verification-loop` | Part of verification loop; finds untested code |
+| `/update-docs` | `update-docs` | Standalone; detects stale docs from code changes |
+| `/diff-explain` | None | Standalone; explains diffs by intent |
+| `/explain-code` | None | Standalone; layered explanation by complexity |
+| `/prompt-test` | None | Standalone; tests LLM prompts against samples |
+| `/ai-engineer-review` | None | Standalone; architectural review |
+| `/changelog` | None | Standalone; generates changelog from commits |
+| `/dep-check` | None | Standalone; audits dependencies |
+| `/env-check` | None | Standalone; validates local dev environment |
+
+## Removed Skills
+
+**`redhat-writing`** — Deleted. This was user-specific (Red Hat brand voice/style). Does not belong in a generic meta-repo that others clone. Users who need it should add their own CLAUDE.md instructions locally.
+
+**`python-conventions` (merged)** — Consolidated into `python-patterns` with `data-pipeline-patterns`. Both covered Python team conventions; one unified skill is clearer.
+
+**`data-pipeline-patterns` (merged)** — Consolidated into `python-patterns`. Pipeline structure is a specific application of Python conventions, not separate.
+
+## Token Budget
+
+Always-loaded skills (loaded once per session):
+- `verification-loop` — ~3KB (core engine)
+- `refactoring-patterns` — ~2KB
+- `security-check` — ~2KB
+- `python-patterns` — ~4KB (credentials, APIs, testing, pipelines)
+- `brainstorming` — ~2KB
+- `cost-speed-meter` — ~4KB
+
+**Total always-loaded: ~17KB** — under 5% of typical conversation context.
+
+On-demand skills (load only when invoked):
+- `update-docs` — ~8KB (detailed multi-step process)
+
+## Design Rationale
+
+1. **Merged python-conventions + data-pipeline-patterns** — Both were "team conventions for Python code." Keeping them separate created confusion about scope. One unified `python-patterns` skill is clearer and avoids redundancy.
+
+2. **Explicit activation in ai-workspace.toml** — Skills can now be tracked as dependencies. Commands that require a skill have it documented. Future refactoring is safer.
+
+3. **Removed redhat-writing from repo** — Generic meta-repo should not include user-specific or organization-specific content. Red Hat employees can add this locally to `~/.claude/CLAUDE.md`.
+
+4. **Clarified brainstorming and cost-speed-meter** — Both had vague triggers ("when to activate"). Rewritten with explicit user-facing conditions (what the user asks for, not implicit context).
+
+5. **Consolidated core verification** — Multiple commands (`/verify`, `/quality-gate`, `/refactor-safe`) all use `verification-loop`. Having them as separate commands is fine; they invoke the same skill with different phase subsets.

ai-workspace.toml

@@ -18,3 +18,28 @@ commands_paths = [
 # Cursor does not parse command frontmatter as metadata
 [distribution.commands_overrides]
 ".cursor/commands" = "strip_frontmatter"
+
+# Skill activation: explicit triggers and command dependencies
+[skills]
+# Skill-to-commands mapping: which commands invoke which skills
+verify = ["verification-loop"]
+quality-gate = ["verification-loop"]
+refactor-safe = ["verification-loop", "refactoring-patterns"]
+test-coverage = ["verification-loop"]
+update-docs = ["update-docs"]
+diff-explain = []  # standalone command
+explain-code = []  # standalone command
+prompt-test = []  # standalone command
+ai-engineer-review = []  # standalone command
+
+# Skills load declaratively (no manual trigger needed)
+# auto-activating = true means description-based activation in CLAUDE.md
+# Set to false if this skill should only load when explicitly invoked
+[skills.auto-activate]
+security-check = true  # Triggers when editing code that handles credentials/APIs
+verification-loop = true  # Powers multiple commands, loads on-demand
+python-patterns = true  # Triggers when editing Python code
+refactoring-patterns = true  # Triggers when refactoring
+brainstorming = true  # Triggers when user asks for design/planning
+cost-speed-meter = true  # Tracks all command execution automatically
+update-docs = false  # Activated via /update-docs command

skills/brainstorming/SKILL.md

@@ -1,38 +1,42 @@
 ---
 name: brainstorming
-description: "Use when the user asks to design, plan, or explore approaches before implementing — creating features, building components, or adding functionality that would benefit from design exploration first."
+description: "User asks for design, planning, or approach exploration before implementation. Covers new features, components, refactors, or architecture decisions. Creates design docs and proposes approaches with trade-offs."
 ---
 
-# Brainstorming Ideas Into Designs
+# Brainstorming — Design Exploration
 
-Help turn ideas into fully formed designs through collaborative dialogue.
+Turn ideas into fully formed designs through collaborative dialogue.
 
-When this skill activates, present a design before writing code. The design can be short (a few sentences for simple projects) — scale it to the complexity of the task. Get the user's approval before proceeding to implementation.
+When triggered, present a design before implementation. The design scales to complexity: short (few sentences) for simple tasks, detailed (pages) for architectural changes. Always get approval before proceeding to code.
+
+## When to Activate
+
+- User explicitly asks: "design this", "how should i build", "what's the approach", "plan this out"
+- User describes a feature/component/refactor and asks for guidance before coding
+- User wants to explore trade-offs or multiple approaches to a problem
 
 ## Process
 
-1. **Explore context** — check files, docs, recent commits
-2. **Ask clarifying questions** — one at a time, prefer multiple choice, understand purpose/constraints/success criteria
-3. **Propose 2-3 approaches** — with trade-offs and your recommendation
-4. **Present design** — scale each section to its complexity, ask after each section if it looks right
-5. **Write spec** — save to `docs/specs/` (create directory if needed) and commit
-6. **User reviews spec** — wait for approval before proceeding
-7. **Transition** — invoke writing-plans skill to create implementation plan
+1. **Explore context** — check relevant code files, docs, recent commits
+2. **Ask clarifying questions** — one at a time, prefer multiple choice, understand: purpose, constraints, success criteria, scope
+3. **Propose 2-3 approaches** — name each, describe trade-offs, state your recommendation
+4. **Present design** — scale to complexity (1-2 sentences for trivial, multiple sections for architecture), ask approval after each section
+5. **Get approval** — wait for user buy-in before writing code
 
 ## Design Principles
 
-- **One question at a time** — don't overwhelm with multiple questions
+- **One question at a time** — don't overwhelm
 - **YAGNI ruthlessly** — remove unnecessary features
-- **Design for isolation** — break into units with one clear purpose, well-defined interfaces, testable independently
-- **Explore alternatives** — always propose 2-3 approaches before settling
-- **Scope check** — if the request describes multiple independent subsystems, decompose into sub-projects first
+- **Design for isolation** — break into units with one purpose, well-defined interfaces, independently testable
+- **Explore alternatives** — always 2-3 approaches, with trade-offs
+- **Scope check** — if request spans multiple subsystems, decompose first
 
-## Working in Existing Codebases
+## In Existing Codebases
 
-- Explore the current structure before proposing changes. Follow existing patterns.
-- Where existing code has problems that affect the work, include targeted improvements as part of the design.
-- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+- Explore current structure and patterns before proposing changes
+- Include targeted fixes only if they block the current goal
+- Don't propose unrelated refactoring
 
-## After Design Approval
+## Output
 
-Invoke the writing-plans skill to create a detailed implementation plan. Do NOT invoke any other skill — writing-plans is the next step.
+Present design as prose (short or detailed based on complexity), then ask: "Does this look right?" Wait for approval before proceeding to implementation.

skills/cost-speed-meter/SKILL.md

@@ -1,22 +1,21 @@
 ---
 name: cost-speed-meter
-version: "1.0"
-description: Track command execution time across sessions. Show which operations are slow, suggest faster paths (unit tests vs integration, cached builds), and measure if optimizations worked. Polyglot language support (Python, Node, Rust, Go).
+description: Track command execution times and suggest faster paths. After tests/builds/lint, shows execution cost and recommends fast-path alternatives (unit tests vs integration, cached builds). For feedback loop optimization and proving optimizations worked.
 ---
 
-# Cost & Speed Meter Skill
+# Cost & Speed Meter
 
-Track what's slow. Measure improvements. Suggest faster paths.
+Track execution time. Suggest faster paths. Prove optimizations worked.
 
-Every bash command execution is timed and stored. Across sessions, you see trends: is your test suite getting slower? Did that optimization work? Should you run unit tests instead of the full suite for quick feedback?
+Every bash command is timed and stored. Across sessions, you see trends: is the test suite slower? Did that optimization help? Should you run unit tests instead of full integration tests for faster feedback?
 
-## When to Activate
+## When to Use
 
-- After running tests, builds, or lint (timing is tracked automatically)
-- When focused on feedback loop speed (which path is fastest?)
-- When investigating performance regressions (did something get slower?)
-- Before/after optimization work (prove it helped)
-- Multi-repo work (compare speed across projects)
+- User runs tests, builds, or lint commands — timing is tracked automatically
+- User asks: "is this slow?", "how long did that take?", "what's the slowest operation?"
+- User asks: "what's a faster way to do this?", "what's the quick feedback loop?"
+- User is optimizing something — measure before, optimize, measure after to prove it worked
+- Working across multiple repos — compare execution costs
 
 ## What It Tracks