Skip to content

skills-reference.md

Latest commit

 

History

History
272 lines (191 loc) · 7.74 KB

skills-reference.md

File metadata and controls

272 lines (191 loc) · 7.74 KB

Skills Reference

Skills are markdown instruction files loaded by AI agents (Claude Code, Gemini CLI, Cursor). They define exactly what the agent should do — what commands to run, what files to read, how to respond.

Skills live in .wednesday/skills/. Each has a SKILL.md with frontmatter permissions and step-by-step instructions.

Brownfield Intelligence Skills

brownfield-chat

When to use: Any natural-language question about the codebase spanning more than one file.

Triggers automatically for:

  • "What does X do?"
  • "What calls Y?"
  • "What breaks if I change Z?"
  • "Who owns the auth layer?"
  • "Which files have the highest risk?"

How it works:

  1. Classifies the question type with zero-LLM regex matching
  2. Routes to the appropriate deterministic handler (symbol lookup, BFS, git log, etc.)
  3. Only calls LLM if the question genuinely requires synthesis (complex multi-step)

Zero token cost for: blast-radius, summary-lookup, symbol-blast, git-history, graph-filter, path-traversal questions.

brownfield-fix

When to use: Before editing any file in a brownfield project.

What it does:

  1. Checks the risk score for the target file (wednesday-skills score <file>)
  2. Runs blast radius to show all dependent files (wednesday-skills blast <file>)
  3. If risk > 80 (Critical): pauses, lists all affected files, requests developer confirmation
  4. If gaps exist: runs fill-gaps for the target file before proceeding

Use it like this:

"Fix the token expiration bug in src/auth/token.ts"

The agent will invoke brownfield-fix automatically before writing any code.

brownfield-drift

When to use: Before merging a PR that crosses module/service boundaries, or as a CI check.

What it does:

  1. Reads boundary rules from PLAN.md (machine-readable constraint blocks)
  2. Checks every edge in the graph against the rules
  3. Reports violations with the commit that introduced them
  4. Optionally suggests fixes

Constraint format in PLAN.md:

[ARCHITECTURE_CONSTRAINTS]
- services/auth → services/core: ALLOWED
- services/payments → ui/components: FORBIDDEN
- services/* → services/*: ALLOWED (same-layer)
- services/* → db/*: FORBIDDEN (services must go via repositories)
[/ARCHITECTURE_CONSTRAINTS]

brownfield-query

When to use: Direct structural lookup about a single file — what it imports, what imports it, its exports, its risk score.

Faster than brownfield-chat for single-file questions because it skips the classification step.

brownfield-gaps

When to use: When brownfield-chat or brownfield-query returns "not mapped" or "gap detected" for a specific file.

What it does:

  • Runs fill-gaps --file <target> via Haiku subagents
  • Resolves dynamic require(variable), import(computed), EventEmitter patterns
  • Only adds edges with confidence ≥ 0.80

brownfield-enrich

When to use: After map, before summarize. Enriches comment intel with LLM-inferred techDebt and isBizFeature signals.

What it does:

  • Reads .wednesday/codebase/analysis/comments-raw.md
  • Calls Haiku on each directory's comments
  • Writes enriched signals back to comments.json
  • These signals feed into risk scoring and MASTER.md

Git & PR Skills

git-os

When to use: Every time a commit is about to be created. This skill is mandatory for all agents in this project.

Enforces:

  • Conventional commit format: type(scope): Description
  • Types: feat, fix, chore, refactor, test, docs, style, perf
  • Imperative mood ("Add login", not "Added login")
  • No AI fingerprints (no Co-Authored-By, no "Generated by Claude" lines)
  • Atomic commits — one logical change per commit
  • Branch naming: feat/, fix/, chore/ prefixes

pr-create

When to use: When creating a pull request.

What it does:

  1. Validates the branch follows GIT-OS naming
  2. Runs a pre-push checklist (tests passing, no console.logs, etc.)
  3. Reads all commits since branch diverged from main
  4. Generates a GIT-OS-compliant PR title and body
  5. Detects stacked branches
  6. Pushes and creates the PR via gh CLI

pr-review

When to use: When PR review comments need to be addressed.

What it does:

  1. Fetches review comments from GitHub (human or Gemini bot)
  2. Categorizes by impact: security > correctness > performance > style
  3. Posts a prioritized fix queue
  4. Applies fixes on developer approval
  5. Creates one atomic commit per fix (GIT-OS format)

sprint

When to use: When starting work on a ticket.

Input: Ticket ID + title/description

Output:

  • GIT-OS branch name: feat/TICKET-123-short-description
  • PR title: feat(scope): Add short description (#TICKET-123)
  • PR body template with sections: Summary, Test Plan, Screenshots

Code Quality Skills

wednesday-dev

When to use: For any TypeScript/React/Next.js development.

Enforces:

  • Import ordering: external → internal → relative → types
  • Function/component complexity limit: max 8 (cyclomatic)
  • Naming: camelCase for functions/variables, PascalCase for components/classes
  • No any types without explicit justification
  • No inline styles in components
  • No magic numbers — use named constants

wednesday-design

When to use: For any UI component or page development.

Enforces:

  • 492+ approved UI components must be used before creating custom ones
  • Design tokens for colors, spacing, typography — never hardcoded values
  • Animation patterns: only approved transitions
  • Accessibility: ARIA labels, keyboard nav, focus management
  • No custom CSS unless absolutely necessary

Architecture Skills

greenfield

When to use: Starting a new project from scratch with a product idea.

What it does:

  1. Research agent builds domain context first
  2. Three agents run in parallel:
    • Architect — system design, service boundaries, data models
    • PM — user stories, phased tickets, success metrics
    • Security — threat model, auth strategy, compliance requirements
  3. Synthesis agent combines all perspectives into PLAN.md
  4. PLAN.md includes a Tensions section documenting architectural trade-offs

deploy-checklist

When to use: Before and after every deployment.

Pre-deploy checklist:

  • All env vars set in target environment
  • Database migrations reviewed and reversible
  • CI is green on the deploy branch
  • Rollback plan documented
  • Smoke test URLs identified

Post-deploy checklist:

  • Smoke tests passing
  • Error rate within baseline
  • Key metrics not regressing
  • Rollback triggered if error rate spikes

How Skills Load

Skills are injected into agent config files during install:

Claude Code (CLAUDE.md):

<available_skills>
  <skill>
    <name>brownfield-chat</name>
    <description>...</description>
    <location>.wednesday/skills/brownfield-chat/SKILL.md</location>
  </skill>
  ...
</available_skills>

When the agent sees a relevant question or task, it reads the SKILL.md file at the listed path to load the full instructions. The skill file includes:

  • Step-by-step workflow
  • Exact wednesday-skills commands to run
  • Output format expectations
  • Permissions (which tools are allowed)

Writing a Custom Skill

Create .wednesday/skills/my-skill/SKILL.md:

---
name: my-skill
description: One-line description of what this skill does
permissions:
  allow:
    - Bash(wednesday-skills blast *)
    - Read(.wednesday/codebase/*)
---

# My Skill

## When to use
Describe the trigger condition.

## Steps
1. Run `wednesday-skills blast {{file}}`
2. Read `.wednesday/codebase/dep-graph.json`
3. Output the result in this format: ...

Then run wednesday-skills sync to inject it into all agent config files.