This repository hosts skill specs and guidance that interoperate with the Superpowers skills system. It is intentionally lightweight and avoids duplicating the upstream skill library.
Taskboard: https://github.com/mcj-coder/development-skills/issues
- Backlog and specification of new skills to be implemented.
- Documentation and references for skills that integrate with Superpowers.
- A place to record decisions without copying the upstream skills.
Install this skill library by creating a symlink from your agent's skill directory to this repository.
- Git (for cloning)
- Superpowers installed (installation guide)
Unix/macOS:
git clone https://github.com/mcj-coder/development-skills.git ~/repos/development-skillsWindows PowerShell:
git clone https://github.com/mcj-coder/development-skills.git $env:USERPROFILE\repos\development-skillsCreate the skills directory if it does not exist:
Unix/macOS:
mkdir -p ~/.claude/skills # For Claude Code
mkdir -p ~/.codex/skills # For CodexWindows PowerShell:
New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills" -Force # For Claude Code
New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex\skills" -Force # For CodexUnix/macOS (Claude Code):
ln -s ~/repos/development-skills ~/.claude/skills/development-skillsUnix/macOS (Codex):
ln -s ~/repos/development-skills ~/.codex/skills/development-skillsWindows (Claude Code) - Run as Administrator:
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\development-skills" -Target "$env:USERPROFILE\repos\development-skills"Windows (Codex) - Run as Administrator:
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.codex\skills\development-skills" -Target "$env:USERPROFILE\repos\development-skills"Note: On Windows, creating symlinks requires Administrator privileges or Developer Mode enabled.
Confirm the symlink was created and skills are discoverable:
Unix/macOS:
ls -la ~/.claude/skills/development-skills # Claude Code
ls -la ~/.codex/skills/development-skills # CodexWindows PowerShell:
dir "$env:USERPROFILE\.claude\skills\development-skills" # Claude Code
dir "$env:USERPROFILE\.codex\skills\development-skills" # CodexTest skill loading: In your agent, try loading development-skills:skills-first-workflow
CRITICAL: Follow a clean build principle. When changes are committed there should be 0 warnings or errors. During development there should be no unresolved warnings such as during git commits or package management operations. Warnings must be resolved immediately.
TDD is mandatory for all changes, including documentation. This repo does not allow "verify after" changes.
- No production change without a failing test first.
- For docs, the "test" is a BDD checklist of expected statements. The checklist must fail against current docs before edits begin.
- Record the failure reason (missing section, missing rule, incorrect wording) before editing.
- Only after the failing checklist is established may implementation begin.
Verification Types:
- Concrete changes (code, config, documentation files): Require applied evidence with commit SHAs and file links. See BDD Checklist Templates for concrete changes template.
- Process-only (planning, reviews, requirements): Analytical verification acceptable with issue comment links. See BDD Checklist Templates for process-only template.
How to determine: Did the work modify files in the repository? Yes = Concrete, No = Process-only.
This repository enforces a skills-first workflow where prerequisite skills must be loaded before implementation begins.
See AGENTS.md for:
- Complete skills-first workflow enforcement rules
- Prerequisites loading order
- Bootstrap instructions for Superpowers
- Process skills required before implementation
Follow a clean, documentation-first style.
- Ensure
.editorconfigformatting is enforced. - Linting and Static Analysis Tools must be run and passing cleanly before committing.
- Naming: use kebab-case for directories and files (for example,
skill-creator/). - Keep files small and scoped; prefer one concept per file.
There is no testing framework in place, so skills testing will need to be "simulated". Tests should be defined in a BDD manner with a list of easily understood assertions to prove success.
When tests are added, colocate them in the skills folder:
- Use clear file naming (for example,
skill-name.test.mdorskill-name.test.js).
- Use the GitHub Flow branching strategy.
- Use concise Conventional Commit messages.
- All tickets should be implemented within a separate transient branch.
- Sub-tasks should be implemented in a branch from the main ticket feature branch.
- When a sub-task is verified and complete the related branch should be merged back into the feature branch.
- When a ticket has all sub-tasks completed and verified it should be merged back into the default branch via PR.
- Before closing a PR, rebase on the latest default branch.
- If commit count is excessive for the PR scope, use squash and merge. Otherwise, rebase and use fast-forward only merge.
- Squash commit messages must be Conventional Commits with a concise description
of the PR changes. Add a footer reference to the relevant ticket when
appropriate (for example,
Refs: #123).
- Do not commit secrets or API keys.
- Keep prerequisites explicit (for example, "superpowers installed") in
README.md.
MANDATORY: All skills in this repository MUST follow the agentskills.io specification.
Requirements for all skills:
- Skills must be in their own directory under
skills/ - Each skill must have a
SKILL.mdfile following the agentskills.io format - Each skill must have a colocated test file (e.g.,
skill-name.test.md) - Skills must include BDD-style tests with RED/GREEN scenarios
- Skills must be interoperable with the Superpowers skill system
- Reference the agentskills.io specification for any formatting questions
| Skill | Description |
|---|---|
agents-onboarding |
Creating AGENTS.md for fresh agent context enablement |
automated-standards-enforcement |
P0 foundational for automated quality (linting, spelling, SAST) |
best-practice-introduction |
Introducing best practices to teams and codebases |
issue-driven-delivery |
Issue-driven workflow (requires ticketing CLI: gh/ado/jira) |
pair-programming |
Human-agent pair programming with review loops |
persona-switching |
P2 multi-identity Git/GitHub workflows with role-based personas |
process-skill-router |
Routing to appropriate process skills based on context |
requirements-gathering |
Creating work items with requirements (no design docs) |
skills-first-workflow |
Skills-first execution workflow (requires Superpowers) |
| Skill | Description |
|---|---|
architecture-testing |
Validating architecture constraints with tests |
component-boundary-ownership |
Defining and enforcing component boundaries |
contract-consistency-validation |
Validating API contracts and breaking changes |
greenfield-baseline |
Setting up new projects with proper foundations |
safe-brownfield-refactor |
Safely refactoring legacy codebases |
scoped-colocation |
Organising code with scoped colocation patterns |
walking-skeleton-delivery |
P3 delivery skill for minimal E2E architecture validation |
| Skill | Description |
|---|---|
broken-window |
Preventing broken window syndrome in codebases |
ci-cd-conformance |
Ensuring CI/CD pipeline compliance |
documentation-as-code |
Treating documentation with same rigour as code |
incremental-change-impact |
Understanding and managing change impact |
markdown-author |
Proactive markdown linting and spelling validation |
quality-gate-enforcement |
Enforcing quality gates in CI/CD pipelines |
static-analysis-security |
Static analysis for security (SAST, vulnerability detection) |
| Skill | Description |
|---|---|
agent-workitem-automation |
Automating work items (requires work item system CLI) |
branching-strategy-and-conventions |
Git branching strategies and conventions |
change-risk-rollback |
Managing change risk with rollback strategies |
deployment-provenance |
Tracking deployment provenance and audit trails |
finishing-a-development-branch |
Completing and integrating development work |
impacted-scope-enforcement |
Enforcing that changes only affect intended scope |
local-dev-experience |
Optimising local development experience |
monorepo-orchestration-setup |
Setting up and orchestrating monorepos |
observability-logging-baseline |
Establishing observability and logging baselines |
release-tagging-plan |
Release tagging strategies and versioning plans |
runtime-tooling-validation |
Validating runtime dependencies and environment setup |
| Skill | Description |
|---|---|
innersource-governance-bootstrap |
Setting up innersource governance practices |
library-extraction-stabilisation |
Extracting and stabilising reusable libraries |
repo-best-practices-bootstrap |
Bootstrapping repository best practices |
security-processes |
Security processes and compliance |
technical-debt-prioritisation |
P3 delivery skill for evidence-based debt prioritisation |
| Skill | Description |
|---|---|
aspire-integration-testing |
Integration testing with .NET Aspire |
csharp-best-practices |
C# language best practices |
dotnet-bespoke-code-minimisation |
Minimising custom code in .NET projects |
dotnet-best-practices |
.NET platform best practices |
dotnet-domain-primitives |
Domain primitives and value objects in .NET |
dotnet-efcore-practices |
Entity Framework Core best practices |
dotnet-healthchecks |
Health checks implementation in .NET |
dotnet-logging-serilog |
Structured logging with Serilog |
dotnet-mapping-standard |
Object mapping standards in .NET |
dotnet-open-source-first-governance |
Open source first approach for .NET |
dotnet-source-generation-first |
Source generation patterns in .NET |
dotnet-specification-pattern |
Specification pattern implementation |
dotnet-testing-assertions |
Testing assertions and patterns in .NET |
testcontainers-integration-tests |
P1 integration testing with Testcontainers |
testing-strategy-dotnet |
.NET-specific testing strategy |
| Skill | Description |
|---|---|
testing-strategy-agnostic |
Language-agnostic testing strategy |
This repository follows standard InnerSource/OpenSource documentation practices:
- CONTRIBUTING.md - How to contribute and create skills
- CODE_OF_CONDUCT.md - Community standards and enforcement
- GOVERNANCE.md - Decision-making process and maintainer responsibilities
- docs/getting-started.md - Developer onboarding and project setup
- docs/architecture-overview.md - Architectural patterns, boundaries, and structure
- docs/coding-standards.md - Code style, naming conventions, and patterns
- docs/testing-strategy.md - Testing approach, tools, and patterns
- docs/exclusions.md - Explicitly excluded patterns and suppressions
- docs/roles/ - Team role definitions for code reviews and expert perspectives
- docs/adr/ - Architecture Decision Records for major decisions
- Skills are in skills/ - Agent-facing skill specifications
- Check docs/exclusions.md before suggesting patterns that may have been declined
- Document using human terminology - When applying skills, update human-readable docs (architecture-overview.md, coding-standards.md, etc.) not skill-specific files
- See AGENTS.md for agent-specific execution rules and documentation standards
GitHub Actions workflows that automate repository processes:
| Workflow | Trigger | Description |
|---|---|---|
| auto-unblock.yml | Issue closed | Removes blocked label from dependent issues |
| backlog-health.yml | Scheduled (weekly) + Manual | Generates health report identifying issues needing attention |
| check-issue-reference.yml | Pull request | Validates PR commits reference GitHub issues |
| detect-duplicates.yml | Issue opened | Detects potentially duplicate issues on creation |
| sync-project-status.yml | Issue label/state changes | Syncs issue state labels to Project board status |
| validate-labels.yml | Issue label/state changes | Validates required labels before state transitions |
See docs/playbooks/ for detailed setup and usage instructions.