Development Skills

PR Checks Project Fitness Review

Reusable skills for Cursor, Claude Code, VS Code (Copilot), and pipelines (GitHub Agentic Workflows, Claude Code Action). The collection covers two areas:

Project fitness review — score a codebase across architecture, security, reliability, testing, performance, algorithms, data, accessibility, and process. Based on guidance from the Fundamentals series.
General development — everyday authoring skills (e.g. generating conventional commit messages) that work in any project, adapting to the project's own language and tooling.

Repository: github.com/jeffabailey/skills

→ SETUP.md — Full setup guide for pipelines and IDEs (Cursor, Claude Code, VS Code, Neovim/Avante).

This repository and the article Fundamental Skills on jeffbailey.us are cross-linked: the article explains the design, trade-offs, and how the skills fit together; this repository contains the installable skill definitions and checklists.

Skills

General development

Skill	Purpose	Triggers
`generate-commit`	Generate a conventional commit message from staged changes, review before committing. Detects the project's language/formatter and applies it.	"generate commit", "write a commit message", "commit my changes"
`ai-sanitize`	Removes AI tells from prose, UI code, and graphics (performative phrasing, emdashes, gradients, glass, eyebrows, pills, emoji, broken ASCII art), extending the project's own style guide and design system. Edits in place or reports only.	"remove AI tells", "de-slop this", "make this UI look less AI-generated"
`fitness-config-init`	Creates a `fitness-config.json` with review weights that fit what the project is for. Scans the folder (or runs a full review first, if asked), proposes weights from a matching purpose profile, explains every change, and saves only the proposal you approve.	"create a fitness config", "tune review weights for this project", "initialize fitness config"

Project fitness review

Skill	Scores	Triggers
`review-architecture`	Coupling, Cohesion, Layering, Modularity, Naming, API Design, Maintainability	"architecture review", "coupling and cohesion", "check code structure"
`review-security`	Input Validation, Auth, Data Protection, Dependencies, Error Handling, Crypto	"security review", "check vulnerabilities", "audit security"
`review-reliability`	Observability, Availability, Timeouts, CI/CD, Incident Readiness, Capacity, Deploy	"reliability review", "production ready", "check observability"
`review-testing`	Pyramid Balance, Test Quality, Coverage, Perf Testing, Debugging, CI Integration	"review test quality", "testing strategy", "test pyramid"
`review-performance`	Algorithmic Efficiency, Database Design, Caching, Scalability, Resources, Pipelines	"performance review", "N+1 queries", "scalability analysis"
`review-algorithms`	Algorithm Choice, Data Structure Selection, Complexity, Concurrency Safety, Edge Cases, Correctness	"algorithm review", "concurrency safety", "correctness check"
`review-data`	Schema Design, Migration Safety, Data Integrity, Query Correctness, Data Modeling, Pipeline Quality	"data review", "schema design", "migration safety"
`review-accessibility`	Semantic HTML, Keyboard Nav, Screen Reader, Color/Contrast, Progressive Enhancement, Responsive, Usability	"accessibility review", "a11y check", "WCAG compliance"
`review-process`	Documentation, Workflow, Code Review, Dependencies, Organization, Portability, Leadership	"process review", "repo health", "development practices"
`review-maintainability`	Structural Complexity, Understandability, Technical Debt, Coupling Depth, Code Smell Density	"maintainability review", "code complexity", "understandability"
`review-full`	All of the above (weighted average)	"full review", "comprehensive review", "project fitness"
`review-jit-test-gen`	Generates tests (no scores)	"generate tests", "write tests for changes"
`review-apply`	Applies fitness report findings (no scores)	"apply review", "address review feedback", "fix review issues"
`review-usability`	Learnability, Efficiency, Memorability, Error Prevention, Satisfaction. Walks a live URL, not source code, so it is not part of `review-full`. Downloads the current usability article to set its rubric.	"usability review of a website", "improve site usability", "task walkthrough"

Each review skill produces scores (1-10) with file:line evidence and prioritized action items. General-development skills produce artifacts (commits, tests, edits) rather than scores.

Installation

See SETUP.md for pipelines and IDE setup (Cursor, Claude Code, VS Code, Neovim/Avante).

Claude Code

This repository is an Agent Plugin (plugin.json at the root, skills under skills/). It also ships Claude Code plugin and marketplace manifests in .claude-plugin/, so you can install it for every Claude Code session:

claude plugin marketplace add jeffabailey/skills   # or a local clone path
claude plugin install jbb-skills@jbb --scope user

Skills are namespaced by the plugin, e.g. /jbb-skills:review-full. After pulling changes, run claude plugin marketplace update jbb && claude plugin update jbb-skills@jbb.

Alternatively, symlink the skills with the install script (see SETUP.md):

bash ~/Projects/skills/scripts/install-skills.sh --clone ~/Projects/skills ~/.claude/skills

Cursor

bash ~/Projects/skills/scripts/install-skills.sh --clone ~/Projects/skills ~/.cursor/skills

The script removes an existing clone directory first if present, so re-runs succeed after moving the repo.

Usage

Slash Commands

/review:review-architecture    # Architecture fitness scores
/review:review-security        # Security vulnerability scan
/review:review-reliability     # Production readiness check
/review:review-testing         # Test quality assessment
/review:review-performance     # Performance bottleneck analysis
/review:review-algorithms      # Algorithm and data structure correctness
/review:review-data            # Schema, migration, and data integrity
/review:review-accessibility   # A11y compliance check
/review:review-process         # Development process audit
/review:review-maintainability # Maintainability, complexity, understandability
/review:review-full            # Run all reviews, unified report
/review:review-jit-test-gen    # Generate tests for changed code
/review:review-apply           # Apply fitness report from GitHub issue
/review:review-usability       # Walk a live site's top tasks, score usability

Natural Language

Skills trigger on natural language too:

"Review the architecture of this project"
"Are there any security vulnerabilities?"
"Is this production ready?"
"Check test quality"
"Find performance bottlenecks"
"Check algorithm correctness"
"Review database schema"
"Full review before shipping"
"Generate tests for my changes"

Reports

Domain skills write reports to docs/<domain>-review.md. The full review writes a unified report to docs/fitness-report.md with weighted scoring:

Architecture: 14%
Security: 14%
Reliability: 10%
Testing: 10%
Performance: 10%
Algorithms: 10%
Data: 10% (skipped if no database code)
Accessibility: 8% (skipped for backend-only projects)
Process: 8%
Maintainability: 6%

Customizing thresholds

Place fitness-config.json in your project root to adjust weights, status thresholds, and confidence cutoffs without editing SKILL.md. Skills read it at runtime.

# From your project root (with skills cloned to ~/Projects/skills or similar)
cp ~/Projects/skills/fitness-config.example.json fitness-config.json

# Or use the script (Python 3.6+, works on Windows/macOS/Linux)
python3 ~/Projects/skills/scripts/fitness-config.py init
python3 ~/Projects/skills/scripts/fitness-config.py validate
python3 ~/Projects/skills/scripts/fitness-config.py show

See fitness-config.example.json and fitness-config.schema.json for the schema.

Using the skills in CI / pipelines

GitHub Agentic Workflows (recommended)

Use gh-aw with Claude Code (default), GitHub Copilot, or OpenAI Codex. Add the workflow and configure the secret for your engine:

gh extension install github/gh-aw
gh aw add jeffabailey/skills/fitness-review
gh aw secrets set ANTHROPIC_API_KEY --value "YOUR_KEY"       # Claude (default)
# gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_TOKEN" # Copilot
# gh aw secrets set OPENAI_API_KEY --value "YOUR_KEY"          # Codex
git add .github/workflows/ .github/scripts/ && git commit -m "Add fitness review" && git push

Select the engine from the Run workflow dropdown (default: claude). Reports are created as GitHub issues. See SETUP.md for full pipeline and IDE setup.

Claude Code GitHub Action (alternative)

You can run the project fitness review (or any domain skill) in CI using Claude Code GitHub Actions. The runner must have the skills available so Claude Code can load them.

1. Prerequisites

Add ANTHROPIC_API_KEY to your repository secrets (Settings → Secrets and variables → Actions). Get a key from console.anthropic.com.
Optional: Install the Claude GitHub App for your repo if you want @claude in comments; not required for workflow-triggered runs.

2. Check out the repo and install the skills

Your workflow must check out the repository and install the skills from this repo so Claude Code can find them. Use the install script from this repo:

Same repo (e.g. this repo): after actions/checkout@v4, run
bash scripts/install-skills.sh "$GITHUB_WORKSPACE" "$HOME/.claude/skills".
Separate checkout: checkout this repo (or your fork) with path: skills, then run
bash skills/scripts/install-skills.sh "$GITHUB_WORKSPACE/skills" "$HOME/.claude/skills".

3. Run the Claude Code action with a review prompt

Use the prompt input to request a full review or a specific domain. The action will run in automation mode and use the installed skills.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Run a full project fitness review on this repository. Use the review-full skill. Write the unified report to docs/fitness-report.md."
    claude_args: "--max-turns 15"

To run a single domain (e.g. security) use natural language that triggers that skill:

prompt: "Run a security review of this project using the review-security skill. Write the report to docs/security-review.md."

4. Use the report (optional)

Upload the report as an artifact or commit it in a follow-up step:

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: fitness-report
    path: docs/fitness-report.md
  continue-on-error: true

See Claude Code GitHub Actions and the action usage docs for authentication (e.g. AWS Bedrock, Google Vertex), security, and claude_args (e.g. --model, --max-turns).

Testing the Skills

The tests/ directory contains test plans for validating that the skills themselves work correctly. This is not about reviewing your project -- it is about verifying the skills behave as designed. Run all tests with the claude CLI against a target project.

1. Trigger Tests

Goal: Verify each skill loads when it should and stays silent when it should not.

Test cases are in tests/trigger-tests.md. For each skill, run the "should trigger" phrases and confirm the skill activates, then run the "should NOT trigger" phrases and confirm it does not.

cd /path/to/a/test/project

# Should trigger review-architecture (expect skill to activate)
claude -p "Review the architecture of this project"

# Should NOT trigger review-architecture (expect no skill activation)
claude -p "Fix this bug"

# Should trigger review-data (expect skill to activate)
claude -p "Review database schema"

# Should NOT trigger review-data (expect no skill activation)
claude -p "Check database performance"

# Should trigger generate-commit (expect skill to activate)
claude -p "Write a commit message for my staged changes"

# Should NOT trigger generate-commit (expect no skill activation)
claude -p "Explain what this function does"

A skill passes its trigger tests when it activates for all "should trigger" phrases and does not activate for any "should NOT trigger" phrases.

2. Functional Tests

Goal: Verify each skill produces the correct outcome — structured output with real evidence for review skills, or the correct artifact and side effects for general-development skills.

Test scenarios are in tests/functional-tests.md using Given/When/Then format. Each scenario defines the preconditions, the command to run, and what to check in the output.

cd /path/to/a/test/project

# Test: review-architecture produces scores for all dimensions
claude -p "/review:review-architecture"
# Then check docs/architecture-review.md for:
#   - Scores (1-10) for all 7 dimensions
#   - Each score backed by file:line evidence
#   - Scores below 6 generate action items

# Test: review-security only reports high-confidence findings
claude -p "/review:review-security"
# Then check docs/security-review.md for:
#   - All findings have confidence >= 7/10
#   - Each finding has severity, file:line, and remediation
#   - No false positives for safe patterns

# Test: review-full produces unified report
claude -p "/review:review-full"
# Then check docs/fitness-report.md for:
#   - Overall weighted score
#   - All domain scores in table format
#   - Top 10 prioritized action items

# Test: generate-commit produces a conventional commit and respects confirmation
claude -p "/generate-commit"
# Then check that the skill:
#   - Detected the project's language/formatter and ran the check-only variant
#   - Proposed a `type(scope): description` message matching recent git log style
#   - Waited for explicit confirmation before committing (no commit on abort)
#   - Left no model attribution (e.g. Co-Authored-By) in the message

For review skills, a functional test passes when the output report matches the expected structure, scores include file:line evidence, and findings are accurate (no false positives). For general-development skills, it passes when the produced artifact (commit, tests, edits) is correct and any required confirmation and side effects behave as specified.

3. Performance Comparison

Goal: Confirm the skill improves on an unassisted prompt for the same task.

Compare results with and without the skill on the same project:

# Review skill — without vs. with
claude -p "Review this project for security issues"   # generic prompt, no checklist
claude -p "/review:review-security"                    # structured workflow + rubric

# General-development skill — without vs. with
claude -p "Commit my changes"                          # ad hoc message, no style detection
claude -p "/generate-commit"                            # detects tooling, enforces convention, confirms

Review skills should produce more findings, fewer false positives, consistent scoring, and file:line evidence that the unassisted run lacks. General-development skills should produce more consistent, convention-following output with the intended safety checks (e.g. style detection and confirmation before committing) that an ad hoc prompt skips.

Structure

All skills live under skills/. Install commands symlink each directory in skills/ (no hardcoded list). See skills/ for the current set of skills; each skill is described in its own SKILL.md.

fitness-config.example.json   # Example config for custom thresholds
fitness-config.schema.json    # JSON schema for validation
scripts/
  fitness-config.py           # entry point: validate, init, show, audit (cross-platform)
  fitness_config/             # resolver package the entry point runs; keep it beside the script
skills/
  generate-commit/          # general-development skill (conventional commits)
    SKILL.md
  ai-sanitize/              # general-development skill (removes AI tells)
    SKILL.md
    references/
      prose.md              # Writing tells and rewrites
      ui.md                 # Interface tells, detection patterns, fixes
      graphics.md           # SVG, ASCII, diagram, chart, and image tells
  fitness-config-init/      # general-development skill (purpose-fit fitness-config.json)
    SKILL.md
    references/
      purpose-signals.md    # Fast-scan budget, signals per archetype, confidence levels
      purpose-profiles.md   # Archetype weight profiles and adjustment rules
  review-<domain>/          # one per domain (architecture, security, etc.)
    SKILL.md                # Skill definition (workflow + scoring rubric)
    references/
      checklist.md          # Detailed checklist items with source citations
  review-full/
    SKILL.md                # Orchestrator (no references needed)
  review-jit-test-gen/
    SKILL.md                # Test generator (no references needed)
  review-apply/
    SKILL.md                # Applies fitness report findings (no references needed)
  review-usability/
    SKILL.md                # Live-site usability walkthrough; fetches its rubric article at run time
    references/
      checklist.md          # Observable checks derived from the article
      wisdom.md             # Offline fallback copy of the article (synced weekly)
tests/
  trigger-tests.md          # What phrases should/shouldn't trigger each skill
  functional-tests.md       # Expected behavior for each skill

License

Unlicense (public domain)