fix(skills): add missing required sections to 28 non-compliant skills (#391)

Added missing sections per SKILL-FORMAT.md requirements:
- 4 skills: Added "When to Use" section
- 8 skills: Added "Core Workflow" section
- 15 skills: Added both "When to Use" and "Core Workflow" sections
- 1 skill: Added "Overview", "When to Use", and "Core Workflow" sections

All 55 skills now pass `npm run validate:skills`.

Refs: #390

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: mcj-coder

skills/agent-workitem-automation/SKILL.md

@@ -20,6 +20,25 @@ all times. If you cannot prove context or tooling, stop and fix that first.
 If an issue-driven workflow is required (work item comments, approvals, evidence tracking),
 use `issue-driven-delivery`.
 
+## When to Use
+
+- Agent is asked to autonomously manage a work item (GitHub, Azure DevOps, or Jira)
+- Comment mentions the agent with a task verb (e.g., "manage", "handle", "take", "own")
+- Need to resolve task board source, platform CLI, or step updates
+- Automating delivery flow across ticketing systems
+- Setting up CI/CD workflows triggered by ticket events
+
+## Core Workflow
+
+1. **Discovery**: Read README.md, locate Work Items section, infer platform from URL
+2. **Setup**: Verify CLI is installed and authenticated for the platform
+3. **Load ticket**: Fetch issue details, comments, acceptance criteria, and related PRs
+4. **Execute step**: Determine and execute only the next required step
+5. **Post update**: Comment with Summary, Evidence, Next Step, and Hand-off status
+6. **Update checklist**: Mark completed items in the issue body
+7. **Verify completion**: Use verification-before-completion for all acceptance criteria
+8. **Close or hand-off**: Close when complete with evidence, or hand off to human if blocked
+
 ## End-to-End Autonomous Delivery Flow
 
 Autonomous delivery follows four explicit phases:

skills/agents-onboarding/SKILL.md

@@ -18,6 +18,14 @@ must understand how to work in the repository by reading only AGENTS.md.
 **REQUIRED SUB-SKILL:** `superpowers:brainstorming`
 **REQUIRED SUB-SKILL:** `superpowers:verification-before-completion`
 
+## When to Use
+
+- User integrates AI agents into repository for first time
+- User asks to set up agent guidance, rules, or onboarding documentation
+- Repository is missing agent-specific onboarding docs (no AGENTS.md)
+- Fresh agent context needs to understand repository standards without conversation history
+- Existing AGENTS.md is incomplete or outdated and needs enhancement
+
 ## Core Workflow
 
 1. **Announce** skill and why it applies.

skills/broken-window/SKILL.md

@@ -24,6 +24,16 @@ objective and measurable—there is no "spirit vs letter" escape.
 - Standards violations detected during code review
 - Skills-first repos: Before starting work (validate prerequisites)
 
+## Core Workflow
+
+1. Detect warning, error, or standards violation
+2. Investigate root cause and document finding
+3. Estimate fix time and remaining work time
+4. Apply 2x rule: if fix time < 2x remaining work, fix immediately
+5. If fix time >= 2x remaining work, create tech-debt issue with steps to replicate
+6. Verify warning/error is resolved or issue is created
+7. Continue with original task
+
 ## The 2x Rule
 
 ```dot

skills/component-boundary-ownership/SKILL.md

@@ -17,6 +17,15 @@ components) to scoped-colocation.
 
 **REQUIRED:** superpowers:brainstorming, superpowers:verification-before-completion
 
+## When to Use
+
+- User decides repository organization or restructures codebase
+- User asks where functionality should live (component placement decisions)
+- User reviews or questions existing component boundaries
+- New functionality spans multiple existing components
+- Team ownership changes require boundary realignment
+- Deployment independence needs evaluation for splitting/merging components
+
 ## Core Workflow
 
 1. **Identify candidate boundaries** based on deployment independence, team ownership, coupling analysis, and reuse patterns

skills/csharp-best-practices/SKILL.md

@@ -16,6 +16,25 @@ detects the language/runtime configuration, prefers the newest supported feature
 consults version-specific references progressively from C# 10 upward while respecting
 repository conventions.
 
+## When to Use
+
+- Implementing or refactoring C# code in any .NET project
+- Reviewing C# code for best practice alignment
+- Upgrading code to use newer C# language features
+- Resolving analyzer warnings or style issues
+- Onboarding to an existing C# codebase to understand effective patterns
+
+## Core Workflow
+
+1. **Detect language version**: Check LangVersion in csproj, Directory.Build.props, or infer from TFM
+2. **Record determination**: Document effective C# version and how it was determined
+3. **Load references progressively**: Load reference docs from C# 10 up to the effective version
+4. **Apply highest-priority guidance**: When conflicts exist, newest version guidance wins
+5. **Handle optional analyzers**: Pause and request clarification for optional/contentious rules
+6. **Apply to touched code only**: Avoid unrelated formatting changes unless broader refactor requested
+7. **Validate build and tests**: Ensure changes compile and pass tests
+8. **Emit summary**: Document applied practices and any pending analyzer decisions
+
 ## Intent
 
 Apply C# best practices appropriate to the project's **effective language version**.

skills/dotnet-bespoke-code-minimisation/SKILL.md

@@ -9,13 +9,26 @@ Bias against bespoke internal implementations by preferring mature open-source t
 composable libraries. When custom code is unavoidable, enforce justification rubrics that
 require explicit rationale, ownership, versioning, testing, and security considerations.
 
-## Core
+## When to Use
+
+- Proposals to write internal mappers, code generators, custom build scripts, or DI containers
+- Reviews where new internal tooling or bespoke framework layers are introduced
+- Evaluating whether to build vs buy/adopt for any infrastructure component
+- Reviewing PRs that add custom implementations for common concerns (validation, retries, caching)
+- Architectural decisions involving custom scaffolding or automation scripts
 
-### When to use
+## Core Workflow
 
-- Proposals to write internal mappers, code generators, custom build scripts, custom DI containers,
-  or bespoke framework layers.
-- Reviews where new internal tooling is introduced.
+1. **Identify the concern**: Determine what functionality is being proposed (mapping, validation, CLI, etc.)
+2. **Search for OSS alternatives**: Evaluate mature open-source libraries that solve the same problem
+3. **Compare trade-offs**: Assess maintenance burden, test effort, performance, and community support
+4. **Apply decision framework**: Choose OSS unless clear justification exists for bespoke code
+5. **Require justification rubric**: If bespoke code is proposed, demand explicit rationale,
+   ownership, versioning, tests, and security considerations
+6. **Document decision**: Record OSS evaluation, selection rationale, and maintenance plan
+7. **Verify in PR**: Check that PR includes evidence of OSS evaluation and rubric satisfaction
+
+## Core
 
 ### Defaults
 

skills/dotnet-best-practices/SKILL.md

@@ -50,6 +50,16 @@ Use this skill when you are:
 
 For cross-language or organization-wide security processes, use the `security-processes` skill alongside this one.
 
+## Core Workflow
+
+1. Identify target .NET version and load corresponding version reference
+2. For upgrades, load upgrade-cumulative.md and lts-upgrade-playbook.md
+3. Apply baseline engineering standards (security, reliability, performance, maintainability)
+4. Review code against version-specific recommended patterns
+5. Validate configuration centralisation and analyzer enforcement
+6. Produce target framework recommendation and adoption checklist
+7. Document risks, breaking changes, and required test gates
+
 ## Progressive loading model
 
 1. Read this file (baseline standards + operating procedure).

skills/dotnet-domain-primitives/SKILL.md

@@ -10,12 +10,25 @@ domain models. Conversions to/from primitives are permitted only at explicit bou
 (persistence, transport, serialization), ensuring type safety and validation throughout
 the domain layer.
 
-## Core
+## When to Use
+
+- Designing or reviewing domain models (entities, aggregates, commands/events)
+- Introducing new entity identifiers (CustomerId, OrderId, TenantId, etc.)
+- Working with meaningful primitives that carry validation (EmailAddress, Money, Percentage)
+- Reviewing code where primitive types (Guid, string, int) are used for domain concepts
+- Implementing API boundaries, persistence layers, or serialization
 
-### When to use
+## Core Workflow
 
-- Designing or reviewing domain models (entities, aggregates, commands/events).
-- Any non-trivial service where identifiers and "meaningful primitives" recur across layers.
+1. **Identify primitive obsession**: Locate places where Guid, string, int, or long represent domain concepts
+2. **Define strongly typed IDs**: Create typed ID types using source-generation libraries for entity identifiers
+3. **Define value objects**: Create value objects for meaningful primitives with validation (EmailAddress, Money)
+4. **Establish boundary conversions**: Map to/from primitives only at explicit boundaries (API, persistence, transport)
+5. **Configure serialization**: Add JSON converters, EF Core value converters, and type handlers as needed
+6. **Update service signatures**: Change service methods to accept domain primitives, not raw types
+7. **Add boundary tests**: Test that boundary conversion works and invalid primitives are rejected
+
+## Core
 
 ### Defaults (non-negotiable)
 

skills/dotnet-efcore-practices/SKILL.md

@@ -9,12 +9,26 @@ Standardise Entity Framework Core usage with dedicated migrations projects exclu
 coverage, attribute-linked configuration types for entities, and deterministic configuration
 discovery. This ensures clean separation between business logic and infrastructure scaffolding.
 
-## Core
+## When to Use
+
+- Any solution using EF Core for persistence
+- Adding or modifying DbContext, entity types, or configurations
+- Creating or updating EF Core migrations
+- Setting up code coverage exclusions for infrastructure projects
+- Reviewing PRs that change persistence layer structure
 
-### When to use
+## Core Workflow
 
-- Any solution using EF Core for persistence.
-- Any PR introducing or changing DbContext, entity types, configurations, or migrations.
+1. **Verify project structure**: Ensure migrations are in a dedicated `*.Persistence.Migrations` project
+2. **Configure coverage exclusion**: Add `<ExcludeFromCodeCoverage>true</ExcludeFromCodeCoverage>` to migrations project
+3. **Create configuration types**: Implement dedicated `IEntityTypeConfiguration<T>` for each entity
+4. **Link via attributes**: Use attribute-based discovery to connect entities to their configurations
+5. **Keep DbContext clean**: DbContext applies configurations, not define them inline
+6. **Ensure deterministic ordering**: Configuration scanning uses stable ordering (e.g., by full name)
+7. **Verify coverage gate**: Run tests to confirm migrations project excluded from coverage reports
+8. **Add repository tests**: Use xUnit with `IAsyncLifetime` for async repository testing
+
+## Core
 
 ### Defaults (non-negotiable)
 

skills/dotnet-healthchecks/SKILL.md

@@ -9,12 +9,25 @@ Standardise health check implementation using the AspNetCore.Diagnostics.HealthC
 open-source ecosystem. Prefer battle-tested packages over bespoke probes for liveness, readiness,
 and dependency health endpoints across databases, caches, message brokers, and external services.
 
-## Core
+## When to Use
+
+- Building or modifying ASP.NET Core services that need health endpoints
+- Adding health checks for infrastructure dependencies (databases, caches, brokers)
+- Implementing Kubernetes liveness and readiness probes
+- Reviewing PRs that introduce custom health check implementations
+- Configuring orchestration health semantics for containerised services
 
-### When to use
+## Core Workflow
 
-- Any ASP.NET Core service exposing liveness, readiness, or dependency health endpoints.
-- Any PR introducing health checks for infrastructure dependencies.
+1. **Evaluate Xabaril packages**: Check if AspNetCore.Diagnostics.HealthChecks has a package for the dependency
+2. **Register health checks**: Add checks via `AddHealthChecks()` with appropriate packages
+3. **Separate liveness from readiness**: Tag liveness checks with "live", readiness with "ready"
+4. **Map endpoints**: Configure `/health/live` and `/health/ready` with tag-based predicates
+5. **Configure orchestration**: Set Kubernetes probes to use appropriate endpoints
+6. **Test health checks**: Unit test custom IHealthCheck implementations, integration test endpoints
+7. **Verify with curl**: Use `curl -i` to confirm endpoints return expected status codes
+
+## Core
 
 ### Defaults (strong preference)