◆ skills

13 reusable methodology skills for Claude Code — distributed as a marketplace plugin, available from your terminal, web app, and mobile.

13 skills 1 plugin · v0.1.0 cloud-ready Agent Skills standard
Contents

Sections

Overview Architecture Installation Skills Principles

Docs & Knowledge

recording-decisions registering-contracts maintaining-conventions logging-learnings mapping-codebases

Process & Architecture

practicing-tdd managing-tech-debt improving-architecture auditing-code-quality

Quality Engineering

hardening-tests authoring-tests exploring-quality

Design

designing-ui-ux

Overview

skills is a Claude Code plugin that delivers 13 methodology skills — structured workflows covering Architecture Decision Records, TDD, contract registries, tech-debt management, codebase mapping, architecture auditing, multi-layer QA, and UI/UX design. Each skill ships with a step-by-step workflow, shell helper scripts, and reference guides.

Skills are distributed as a marketplace plugin: declare the marketplace once in a repo's committed .claude/settings.json and every session — local terminal, web app, or mobile — installs the same skills automatically.

marketplace.jsondotts-h/claude-skills
→
skillsplugin · v0.1.0
→
13 skillsSKILL.md + scripts + refs
→
any sessionterminal · web · mobile

Architecture

Repository layout

dotts-h/claude-skills/
├── .claude-plugin/
│   └── marketplace.json    # catalog — registers the plugin
├── plugins/skills/
│   ├── .claude-plugin/
│   │   └── plugin.json     # manifest (name, version, author)
│   └── skills/
│       ├── recording-decisions/
│       │   ├── SKILL.md    # frontmatter + workflow + rules
│       │   ├── references/ # guides & templates (1–5 files)
│       │   └── scripts/    # bash helpers (1–4 scripts)
│       └── … (13 skills total)
├── docs/
│   ├── index.html          # GitHub Pages site
│   └── .nojekyll
└── README.md

Skill anatomy

Every skill follows the same three-part structure:

SKILL.md YAML frontmatter (name, description, allowed-tools) followed by the full workflow: ordered steps, trigger conditions, rules, and inline pointers to reference material.
references/ Markdown guides, templates, and pattern libraries the skill cites — typically 1–5 files. These are the knowledge library Claude reads before acting.
scripts/ Bash helpers the skill runs: allocating numbers, mining signals, running quality gates, computing metrics. Deterministic and idempotent where possible.

SKILL.md frontmatter

---
name: recording-decisions
description: >
  Propose, number, and manage Architecture Decision Records (ADRs)
  using the MADR-lite format under docs/adr/.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

## Workflow
…

Marketplace distribution

The .claude-plugin/marketplace.json file registers the repo as a named marketplace (ori). The plugin.json manifest inside the plugin declares what skills it provides. Cloud sessions read a repo's committed .claude/settings.json and install declared plugins automatically at session start — no local setup needed for web or mobile.

Skills in ~/.claude/skills live only on one machine. A marketplace declared in .claude/settings.json travels with the repo: commit it once and every collaborator's cloud session gets the same skills.

Installation

Via settings.json — persists across all sessions

Add to the repo's committed .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "ori": {
      "source": { "source": "github", "repo": "dotts-h/claude-skills" }
    }
  },
  "enabledPlugins": ["skills@ori"]
}

Commit and push. Any cloud session for that repo installs the plugin automatically at session start.

Interactively in a local session

/plugin marketplace add dotts-h/claude-skills
/plugin install skills@ori

Invoking a skill

Once installed, invoke any skill by typing its name as a slash command:

/recording-decisions
/practicing-tdd
/exploring-quality

Each skill reads docs/CONVENTIONS.md first (if it exists in your repo), then runs its workflow.

Skills

13 skills across 4 groups. Expand any skill to see its full description, workflow, scripts, and reference files.

Docs & Knowledge

recording-decisions MADR-lite Architecture Decision Records under docs/adr/

Propose, number, and manage Architecture Decision Records (ADRs) using the MADR-lite format. ADRs capture the why behind significant decisions — framework choices, patterns, naming conventions, persistence strategies. Once accepted, an ADR is immutable; decisions are recorded as a new ADR that supersedes the old one, never as an edit.

Invoke when you make a significant architectural or design decision worth preserving

Workflow

  1. Read docs/CONVENTIONS.md for any project-specific ADR rules
  2. Run new-adr.sh to allocate the next sequential number and create a stub file
  3. Write the ADR body: context, decision, consequences, and alternatives considered
  4. Mark status as Accepted
  5. Run relink.sh if any supersedes/superseded-by links need updating

Scripts

ScriptPurpose
new-adr.shAllocate the next ADR number and create a stub at docs/adr/NNNN-kebab-title.md
reindex.shRenumber all ADR files sequentially after deletions or re-ordering
relink.shFix supersedes / superseded-by cross-links across all ADR files

Reference files

FileContent
madr-template.mdMADR-lite frontmatter + body template (status, deciders, date, context, decision, consequences)
styles.mdComparison of MADR vs Nygard ADR styles — when to use each
registering-contracts Interface, route, event & schema registry in docs/CONTRACTS.md

Maintain docs/CONTRACTS.md — the single registry of all stable promises between components. Covers Go interfaces, HTTP routes, SSE event types, config schemas, and invariants. Every entry carries a stability marker: stable, internal, or experimental. Breaking a stable contract requires an ADR before the change is made.

Invoke when adding or changing a public interface, route, event type, or schema

Workflow

  1. Classify the contract type (interface / route / event / schema / invariant)
  2. Run extract-interfaces.sh to cross-check all exported Go interfaces against the registry
  3. Add or update the row in CONTRACTS.md with the correct stability marker
  4. For stable → breaking changes: write an ADR first, then update the contract entry

Scripts

ScriptPurpose
extract-interfaces.shGrep exported interfaces from Go source to verify registry coverage
ensure-doc.shCreate CONTRACTS.md with the standard stub if it doesn't exist

Reference files

FileContent
contract-entry-template.mdColumn definitions and example rows for each contract type
detecting-drift.mdHow to spot contract drift at code-review time; checklist of drift signals
maintaining-conventions The project constitution — docs/CONVENTIONS.md

Curate docs/CONVENTIONS.md — the central rulebook that every other methodology skill reads before acting. Contains copy-pasteable commands, exact file paths, coverage floors, merge strategy, naming rules, and environment facts. Rules are not paraphrased; they are copy-pasteable and machine-checkable. Every enforceable rule links back to its ADR.

Invoke when adding a workflow rule, updating a quality gate, or codifying a repeated pattern

Workflow

  1. Run harvest.sh to mine existing TODOs, patterns, and config for convention candidates
  2. Propose the convention in the correct section (see convention-categories.md for the required section set)
  3. Add an ADR backlink if the convention is enforceable
  4. Run check.sh to validate all required sections are present

Scripts

ScriptPurpose
harvest.shMine TODOs, FIXMEs, config keys, and naming patterns to surface convention candidates
check.shValidate CONVENTIONS.md has all required sections and no broken ADR links

Reference files

FileContent
convention-categories.mdRequired sections and their content contracts: workflow, architecture, testing, quality gates, persistence, environment, naming/style
logging-learnings Fixed bugs, dead-ends & gotchas in docs/REGRESSIONS.md

Log fixed bugs and dead-ends to docs/REGRESSIONS.md (or LEARNINGS.md) so the same mistake can't be repeated silently. Three entry types: Fixed (symptom / root-cause / fix / guard-test), Dead-end (tried / why-failed / instead), and Gotcha (unexpected behavior or constraint). Every fixed bug must name the guarding test that prevents recurrence.

Invoke when after fixing a bug, hitting a dead-end, or discovering an unexpected gotcha

Workflow

  1. Run ensure-doc.sh to create the stub if REGRESSIONS.md doesn't exist
  2. Classify the entry type (Fixed / Dead-end / Gotcha)
  3. For bug fixes: name the guarding test — this is mandatory
  4. Write the entry from the appropriate template and append to the document

Scripts

ScriptPurpose
ensure-doc.shCreate REGRESSIONS.md with standard stub and section headers if the file is missing

Reference files

FileContent
entry-templates.mdComplete templates for Fixed, Dead-end, and Gotcha entry types
mapping-codebases Module layout & data-flow map in docs/CODEBASE_MAP.md

Generate docs/CODEBASE_MAP.md — a module table, primary data path (as an arrow chain), and seam identification. The map is an index, not an encyclopedia: it answers "where does X live and how does data move?" then points to ARCHITECTURE.md and CONTRACTS.md for depth. Distinguishes pure-core modules from thin-edge adapters.

Invoke when onboarding, before a cross-cutting refactor, or when "where does X live?" keeps coming up

Workflow

  1. Run module-inventory.sh to get LOC and exported symbol count per package
  2. Write the module table: path, purpose, LOC, exports, pure-core or thin-edge
  3. Trace the primary data path from entry point to output as an arrow chain
  4. Identify the main seams — interfaces where mocks exist or should exist

Scripts

ScriptPurpose
module-inventory.shCompute LOC and exported symbol count per Go package / module

Reference files

FileContent
map-template.mdFull CODEBASE_MAP.md template with all required sections and example rows

Process & Architecture

practicing-tdd Test-first red → green → refactor cycle

Drive development test-first: write a failing test that defines the requirement, write the minimum code to make it pass, refactor under green, then run all quality gates. Tests are written through the seam (the copilot.Client mock interface) — never against internals. Table-driven tests are the default.

Invoke when starting any feature or bug fix

Workflow

  1. Write the failing test first — assert on events/state, not on internal function calls
  2. Confirm it's red before writing any product code (never skip this)
  3. Write the minimum code to make it green
  4. Confirm green
  5. Refactor with confidence — tests stay green throughout
  6. Run gate.sh to execute all project lint, test, and coverage gates

Scripts

ScriptPurpose
gate.shAuto-detect and run all project quality gates (lint, test, coverage floor) in one command

Reference files

FileContent
testing-through-the-seam.mdSeam-based unit testing: MockClient pattern, what to assert on, what to avoid
red-green-refactor.mdTable-driven test structure, discipline rules, and common TDD mistakes
managing-tech-debt Prioritized debt register in docs/TECH_DEBT.md

Record shortcuts, legacy knots, and architecture drift in docs/TECH_DEBT.md. Each row captures description, location, severity, effort, and — most critically — interest (ongoing drag × probability of triggering). Rank by interest, not severity: a medium-severity item that slows every PR has higher priority than a severe item you'll never touch.

Invoke when taking a shortcut, discovering untracked debt, or reviewing before a release

Workflow

  1. Run debt-scan.sh to sweep for TODO/FIXME/HACK with file and line context
  2. Classify each item (architecture / testing / docs / tooling / performance)
  3. Score severity, effort, and interest (ongoing drag × likelihood)
  4. Add rows to TECH_DEBT.md; set a paydown trigger condition for each item

Scripts

ScriptPurpose
debt-scan.shGrep for TODO/FIXME/HACK across the codebase with file and line context
ensure-doc.shCreate TECH_DEBT.md with the standard stub if missing

Reference files

FileContent
debt-register-template.mdTable column definitions, scoring rubric, and example rows
prioritization.mdInterest = probability × ongoing drag; how to score and rank the register
improving-architecture Structural assessment & refactoring — always via ADRs

Assess module boundaries, dependency direction, and coupling. All structural changes are proposed as ADRs — never refactored silently. Checks structure: layer violations, forbidden imports, hidden coupling. Distinct from bug-finding (/code-review) and line-level cleanup (/simplify).

Invoke when coupling concerns surface, before a large refactor, or after mapping the codebase

Workflow

  1. Run deps-check.sh for a per-package import summary and forbidden cross-layer imports
  2. Identify coupling smells using the coupling-smells.md symptom table
  3. Check dependency direction against the allowed rules in dependency-rules.md
  4. Propose the structural change as an ADR using the refactor-as-adr.md template
  5. Implement under the ADR — the decision record is the paper trail

Scripts

ScriptPurpose
deps-check.shPer-package import summary; flags imports that violate layer dependency rules

Reference files

FileContent
coupling-smells.mdSymptom → root cause table for common coupling problems
dependency-rules.mdAllowed import directions by architectural layer
refactor-as-adr.mdTemplate for recording structural changes as Architecture Decision Records
auditing-code-quality Patterns & antipatterns review against project idioms

Review code against Go idioms, the project's pure-core/thin-edges architecture, seam discipline, error handling patterns, and naming conventions. Produces a ranked findings report with file and line references. Distinct from bug-finding (/code-review) and mechanical formatting cleanup (/simplify).

Invoke when pre-merge quality gate, periodic code health check, or onboarding audit

Key antipatterns (ranked by cost)

  1. Seam leak — production type used directly in tests instead of the interface
  2. Punted error — error swallowed, logged-and-continued, or returned as nil
  3. Impure core — telemetry/config/ctxforge package importing business logic
  4. Voodoo constants — magic numbers or strings with no named constant
  5. Inconsistent terminology — same concept named differently across packages
  6. Nondeterminism — map iteration, goroutine ordering, or time.Now() in pure functions
  7. Premature abstraction — interface with one implementation and no test doubles

Scripts

ScriptPurpose
smells.shDetect seam leaks, punted errors, and naming drift via grep patterns

Reference files

FileContent
antipatterns-catalog.mdRanked catalog with symptoms, root causes, and recommended fixes
go-patterns.mdIdiomatic Go patterns the project follows
project-idioms.mdProject-specific naming conventions and style rules

Quality Engineering

hardening-tests SDET audit — coverage gaps, weak assertions, flakes

Audit the test suite as an SDET: identify coverage gaps, assess assertion strength, hunt flaky tests, and detect missing edge/property/fuzz cases. Doesn't write product code — only strengthens tests. Key insight: a line ran is not a line checked; mutation testing is the real coverage bar.

Invoke when pre-release hardening, after a regression, or when mutation scores are low

Workflow

  1. Scan for coverage gaps: uncovered code paths and missing error branches
  2. Assess assertion strength — are tests checking behavior or just "no panic"?
  3. Run flake-hunt.sh to detect non-deterministic failures under the -race flag
  4. Run mutation-run.sh to identify surviving mutants (undertested logic)
  5. Write guard tests for any fixed bugs that are missing coverage

Scripts

ScriptPurpose
flake-hunt.shRun tests N times with -race; collect and report non-deterministic failures
mutation-run.shRun mutation testing; report surviving mutants as undertested logic

Reference files

FileContent
assertion-strength.mdWeak vs. strong assertion patterns; how to upgrade from "no panic" to behavioral checks
flake-hunting.mdIsolation strategies, common root causes, and fixes for flaky tests
mutation-testing.mdReading mutation results, typical survivors, and how to kill them
authoring-tests e2e · API · performance · accessibility test layers

Write higher-level tests across four layers: Playwright end-to-end (real browser, htmx, SSE), API/contract (escaping, cookies, isolation), performance benchmarks (hot paths, latency), and accessibility (WCAG 2.1/2.2). Locator discipline is enforced: role/test-id selectors and web-first assertions only. The demo server is a shared in-memory session — see demo-gotchas.md for isolation pitfalls.

Invoke when a feature is complete and needs e2e, API contract, performance, or a11y coverage

Test layers

LayerScope
e2eReal browser, full user flows, htmx DOM updates, SSE message delivery
api / contractHTTP responses, escaping, cookie handling, cross-endpoint isolation
perfBenchmark hot paths, latency under load, memory allocation
a11yWCAG 2.1/2.2: role attributes, keyboard navigation, focus order, contrast ratios

Scripts

ScriptPurpose
init-agents.shScaffold Playwright agent test files for the target layer
run-layer.shRun a specific test layer: e2e | api | perf | a11y

Reference files

FileContent
test-layers.mdFull taxonomy of test layers: what each covers and when to use each
playwright-agents.mdLocator discipline, web-first assertions, and the Playwright agents workflow
demo-gotchas.mdShared in-memory demo session pitfalls and test isolation strategies
exploring-quality Two-phase exploratory QA → ranked findings report

Two-phase exploratory QA: Phase 1 is breadth — derive the full surface from code, probe all routes headlessly, cheaply. Phase 2 is depth — real browser, curiosity-led investigation using accessibility-tree snapshots to chase anomalies found in Phase 1. Output is a ranked findings report saved to docs/qa/exploratory-<date>.md.

Invoke when pre-release QA pass, after a major feature, or when automated tests can't answer "is this actually good?"

Workflow

  1. Phase 1 (breadth): run surface-inventory.sh to extract all routes → run breadth-sweep.sh to probe them headlessly → collect anomalies
  2. Phase 2 (depth): run launch-demo.sh → open a real browser → investigate top anomalies from Phase 1 with Playwright accessibility-tree snapshots
  3. Compile ranked findings into docs/qa/exploratory-<date>.md using the findings-report template

Scripts

ScriptPurpose
surface-inventory.shExtract all routes and endpoints from source code
launch-demo.shStart the demo server for manual or Playwright-driven testing
breadth-sweep.shScripted headless probe of all surfaces found by surface-inventory.sh

Reference files

FileContent
phase1-breadth.mdHeadless sweep methodology: what to check and how to record anomalies
phase2-deepdive.mdReal-browser curiosity-led investigation: accessibility-tree technique and chase heuristics
findings-report.mdRanked findings report template (severity / impact / reproduction / recommendation)

Design

designing-ui-ux UX heuristics · a11y audit · design tokens · htmx patterns

Full UX/UI design loop: audit UX flows against Nielsen's 10 heuristics and Krug's principles, audit accessibility (WCAG POUR), review visual hierarchy (Refactoring-UI), update design tokens in docs/DESIGN.md, implement, and verify with automated scans. Design tokens as CSS custom properties prevent visual drift. Accessibility wins are locked with automated tests.

Invoke when designing new UI, auditing existing UX, addressing a11y issues, or updating design tokens

Workflow

  1. Audit UX flows against Nielsen/Krug heuristics
  2. Audit accessibility (WCAG POUR: Perceivable, Operable, Understandable, Robust)
  3. Audit visual hierarchy against Refactoring-UI spacing and typography principles
  4. Update design token definitions in docs/DESIGN.md (CSS custom properties)
  5. Implement changes
  6. Run axe-scan.sh to verify a11y compliance; run screenshot-states.sh to capture visual state

Scripts

ScriptPurpose
axe-scan.shRun the axe accessibility scanner against the running demo and report violations
screenshot-states.shCapture key UI states for visual comparison and regression detection

Reference files

FileContent
ux-heuristics.mdNielsen's 10 usability heuristics + Krug's "Don't Make Me Think" principles applied to web UX
wcag-pour.mdWCAG 2.1/2.2 Perceivable/Operable/Understandable/Robust checklist
refactoring-ui.mdVisual hierarchy, spacing, typography, and color contrast principles
design-tokens.mdCSS custom property token schema — how to define, document, and use tokens
htmx-implementation.mdhtmx-specific UX patterns: partial updates, loading states, error feedback

Core Principles

Shared disciplines enforced across all 13 skills:

Documentation as code
Every enforceable rule links an ADR (the why). Docs are the source of truth, not copies of code comments.
Immutable decisions
ADRs are never edited once accepted. A changed decision becomes a new ADR that supersedes the old one.
Deterministic tooling
Scripts compute numbers (ADR allocation, module inventory, debt scores) rather than relying on memory or approximation.
Seam discipline
A defined interface separates testable business logic from network adapters. Tests mock the seam, never the implementation.
Pure core, thin edges
Core packages (telemetry, config, ctxforge) stay dependency-free. All I/O lives in thin adapter packages at the edges.
Contracts as registry
All stable promises (interfaces, routes, events, schemas) live in one table. Breaking a stable contract requires an ADR first.
Interest over severity
Tech debt is ranked by interest (ongoing drag × probability), not by severity alone. High-friction items that slow every PR outrank rare catastrophic ones.
Two-phase QA
Breadth first (cheap, headless, full surface), then depth (real browser, curiosity-led, chasing anomalies). Don't go deep before going wide.
Constitution pattern
docs/CONVENTIONS.md is the single rulebook. Every skill reads it before acting. Rules are copy-pasteable, not paraphrased.