klod68/gen-skill

---

name: gen-skill description: "Use when generating a new skill document for the Truenorth KB — knowledge artifacts that provide domain-specific guidance, templates, patterns, or procedures. Invoked by the Apex Orchestrator in Create mode, or directly when the user asks to create a skill, add a how-to guide, scaffold a best-practices document, or register a new knowledge artifact. Produces a fully compliant SKILL.md with problem statement, context, procedure, examples, and checklist. Domain: KB Evolution, AI Architecture. Level: Advanced. Tags: meta, kb-evolution, skill-generation, apex."

Skill Generator

Problem

The knowledge base grows when new domain guidance, templates, or best-practice procedures need to be captured as reusable skill artifacts. Without a schema and quality checklist, generated skills are inconsistent, incomplete, or duplicate existing guidance.

When to Use

• The Apex Orchestrator is in Create mode and has classified the gap as skill
• The user explicitly asks to create a new skill or knowledge document
• A codebase analyst or technology scout surfaces a gap that warrants a reusable procedure (not just a one-time answer)

Core Distinction: Skill vs. Agent

| Type | Purpose | Invoked by | |---|---|---| | Skill | Provides knowledge, templates, procedures, or patterns | An agent reads it to gain domain knowledge | | Agent | Executes a multi-step task or coordinates other agents | The orchestration pipeline via the task tool |

Choose skill when the artifact is knowledge to apply, not behavior to execute. Choose agent when the artifact needs to run as a tool-calling, decision-making entity.

If unsure: if the thing you are documenting is a step-by-step procedure that an agent reads and follows, it is a skill. If it needs to call other tools or sub-agents autonomously, it is an agent.

---

Skill Categories

Skills fall into these categories. Identifying the category guides the structure:

| Category | Description | Examples | |---|---|---| | Procedure | Step-by-step how-to for a bounded technical task | gen-component, gen-cqrs-handler | | Pattern | Design pattern or architectural approach with examples | agentic-workflow-patterns, caching-strategy | | Configuration | Setup, wiring, or registration guidance | gen-di-composition-root, embedded-resource-configuration | | Analysis | Methodology for investigating or diagnosing a domain | debug-ef-query, ef-query-optimization | | Decision-guide | Framework for choosing among alternatives | api-versioning-strategy, dependency-injection-lifetime | | Template | Scaffold with slots for parameterized generation | gen-gherkin-feature, gen-use-case | | Knowledge | Domain reference, taxonomy, or standards summary | agentic-workflow-patterns |

---

Skill Schema (required sections, in order)

Every SKILL.md must contain these sections. Missing required sections fails Tier 1 quality gate.

---
name: {skill-name-in-kebab-case}
description: "{One to three sentences. First: what the skill covers. Second: when to invoke it.
  Third (optional): related skills or constraints. Quotable as a tool description — concrete,
  specific trigger signals.}"
---

# {Skill Title in Title Case}

## Problem

{1–2 paragraphs describing the problem this skill solves. Written from the consumer's
perspective: what goes wrong without this guidance? What mistake does this skill prevent?}

## When to Use

{Bulleted list of conditions that indicate this skill applies. Include:
- Specific task types or user requests
- Keywords that signal this skill
- Negative conditions (when NOT to use this skill)}

---

## {Core content section — title matches the category}

{The main body. Structure depends on category:

PROCEDURE skills: numbered steps with code examples.
PATTERN skills:   context, pattern description, code skeleton, trade-offs table.
CONFIGURATION:    setup steps with complete, compilable code snippets.
ANALYSIS:         diagnostic steps, what to look for, how to interpret findings.
DECISION-GUIDE:   decision matrix table with criteria and options.
TEMPLATE:         the template body with ${N:placeholder} slots and fill instructions.
KNOWLEDGE:        taxonomy, reference table, or conceptual model.}

---

## Examples

{2–4 concrete examples. Each example:
- States the scenario in one sentence
- Shows input / output or before / after code
- Highlights the key principle the example demonstrates}

---

## Related Skills

- `{skill-slug}` — {one-sentence description of the relationship}
- `{skill-slug}` — {one-sentence description of the relationship}

---

Naming Conventions

Skill ID (directory name and name frontmatter)

• Kebab-case: gen-cqrs-handler, caching-strategy, api-versioning-strategy
• Verb prefix for generation skills: gen-{thing} — gen-component, gen-repository
• Noun phrase for knowledge/pattern skills: {topic}-{qualifier} — circuit-breaker-state-machine
• Never: my-skill, new-skill, skill-for-X (too vague)
• Never: more than 4 segments: gen-complex-thing-v2 (split the concern instead)

Directory Structure

KB/shared/skills/{skill-id}/
└── SKILL.md       ← primary file; all instructional content lives here

Default: Everything in SKILL.md. This is the correct choice for the vast majority of skills.

Exception — Reference Pattern (ecosystem KB only): Skills in KB/shared/skills/ may use optional references/ sub-directories for large static content (≥5KB of verbatim templates, schemas, or scaffolds that the agent copies rather than interprets). Sub-files deploy correctly via ai-context new but are NOT included in ai-context export or ai-context add. See skill-authoring-patterns for the full decision framework.

KB/shared/skills/{skill-id}/
├── SKILL.md                    ← instructions (always required)
└── references/                 ← optional; large verbatim content only
    └── template.md

---

Content Quality Rules

Problem section

• Must describe a real, specific problem — not "this skill helps with X"
• Should name the failure mode: "Without this, developers tend to..."
• 2–4 sentences maximum

When to Use section

• List 3–6 specific conditions — never generic "use this for anything related to X"
• Include at least one negative condition (when NOT to use)
• Keyword signals map to the description frontmatter

Core Content section

• Code examples must be complete and compilable (no ... ellipsis in runnable blocks)
• Use // TODO: only for logic the caller must implement, never as a placeholder for missing content
• Tables must have headers and at least 2 data rows
• Decision matrices must have a recommendation or tie-breaker rule

Examples section

• Required: at least 2 examples
• Each example must be scenario-based, not just a code snippet with no context
• "Good" / "Bad" comparison examples are strongly preferred for anti-pattern skills
• For generation/transformation skills: use few-shot pairs (Input → Output + principle note) rather than illustrative examples. The model pattern-matches from concrete before→after pairs more reliably than from verbose conditional rules. See skill-authoring-patterns for the distinction between illustrative and few-shot examples.

Related Skills section

• Include at least 1 related skill
• Relationships: "use before this", "use after this", "alternative to this", "pairs with this"
• Never self-reference

---

Generation Procedure

0. Choose authoring pattern — before writing anything, decide how to structure the skill's content. See skill-authoring-patterns for the full decision framework:
   • Inline Instructions (default): all content in SKILL.md. Use for rules, procedures, decisions ≤15KB.
   • Reference Pattern: large verbatim content in references/. Use for templates ≥5KB in ecosystem KB skills only.
   • Few-Shot Pattern: input→output example pairs (inline in ## Examples). Use for transformation/generation skills where examples outperform verbose rules.
   • Decomposition: if the planned content exceeds ~15KB, evaluate whether it covers multiple independently triggerable concerns. If so, split into focused skills.
1. Classify the new skill into a category (Procedure, Pattern, Configuration, etc.)
2. Name the skill using the kebab-case conventions above
3. Check for overlap — verify no existing skill covers the same scope:
   • Check the ecosystem KB overlap tables below
   • Check the project KB (ai-context/skills/) for imported skills that may already cover the gap. If a matching imported skill exists, do not generate — recommend using the existing import instead.
   • Check ai-context/.imports.json for provenance of previously imported skills
4. Draft the description frontmatter first — it must be quotable as a tool description before the body is written
5. Write the schema sections in order; do not skip sections
6. Verify all code examples compile as-written
7. Run the generation checklist

---

Overlap Prevention Checklist

Before creating a new skill, verify it does not duplicate an existing one:

Code generation skills

| New skill covers... | Check against... | |---|---| | Generating a component | gen-component | | Generating a CQRS handler | gen-cqrs-handler | | Generating a repository | gen-repository | | Generating a hosted/background service | gen-hosted-service | | Generating a minimal API endpoint | gen-minimal-api-endpoint | | Generating a SignalR hub | gen-signalr-hub | | Generating options/settings class | gen-options-class | | Generating DI composition root | gen-di-composition-root | | Generating a Blazor demo site | gen-blazor-demo-site | | Generating middleware | gen-middleware | | Generating a test class | gen-test-class | | Generating a use case document | gen-use-case | | Generating a user story | gen-user-story | | Generating a Gherkin feature | gen-gherkin-feature | | Generating a service interface | gen-service-interface | | Generating a factory class | gen-factory-class | | Generating global usings | gen-global-usings | | Generating scoped instructions | gen-scoped-instructions | | Generating a worker service | gen-worker-service | | Generating resilience policies | gen-resilience-policy | | Generating embedded config loader | gen-embedded-config-loader | | Generating in-memory demo service | gen-in-memory-demo-service | | Generating copilot instructions | gen-copilot-instructions, gen-verbose-copilot-instructions | | Generating an agent | gen-agent | | Generating a skill | gen-skill |

Review filter skills

| New skill covers... | Check against... | |---|---| | Code review checklists | review-code | | Security review | review-security | | Performance review | review-performance | | Contract/DbC review | review-contracts | | Design fidelity review | review-design-fidelity | | Requirements fidelity review | review-requirements-fidelity | | Maintainability review | review-maintainability | | Testability review | review-testability | | API surface review | review-api-surface | | DI graph review | review-di-graph | | Library architecture review | review-library-architecture | | NuGet packaging review | review-nuget-packaging | | Unix philosophy review | review-unix-philosophy |

Architecture pattern skills

| New skill covers... | Check against... | |---|---| | Agentic workflow selection | agentic-workflow-patterns | | Background work / queues | background-hosted-service | | Caching patterns | caching-strategy | | Circuit breaker / retry | circuit-breaker-state-machine | | Criteria/filter objects | criteria-pattern | | Domain event dispatch | domain-event-dispatch | | Result object pattern | result-object-pattern | | Specification pattern | specification-pattern | | Outbox pattern | outbox-pattern | | Bulk operations / batching | bulk-operation-batching | | Concurrent collections / telemetry | analytics-concurrent-collections | | API versioning | api-versioning-strategy | | DI lifetime selection | dependency-injection-lifetime | | Feature flags | feature-flag-management | | Guard clause validation | guard-clause-validation | | Interceptor pipelines | interceptor-pipeline | | Internal-by-default library design | internal-by-default-library-design | | Pagination strategies | pagination-cursor-offset | | Retry / exponential backoff | retry-exponential-backoff | | Strongly typed IDs | strongly-typed-id |

Infrastructure & DevOps skills

| New skill covers... | Check against... | |---|---| | Embedded resource configuration | embedded-resource-configuration | | EF Core query optimization | ef-query-optimization, debug-ef-query | | Multi-TFM NuGet packaging | multi-tfm-nuget-packaging | | CI/CD pipelines | multi-stage-cicd-pipeline | | OpenTelemetry setup | opentelemetry-setup | | Distributed logging / correlation | distributed-logging-correlation | | Health check endpoints | health-check-endpoint | | Persistence layer implementation | implement-persistence-layer | | Localization / resource files | localization-resource-files | | Middleware pipeline ordering | middleware-pipeline-ordering | | Rate limiting | rate-limiting-middleware |

AI & integration skills

| New skill covers... | Check against... | |---|---| | AI chatbot knowledge injection | ai-chatbot-contextual-knowledge | | Streaming AI responses | streaming-ai-responses | | LLM evaluation | llm-evaluation |

Testing & quality skills

| New skill covers... | Check against... | |---|---| | Test category taxonomy | test-category-taxonomy | | Integration testing with WebApplicationFactory | integration-testing-webapplicationfactory |

Developer experience skills

| New skill covers... | Check against... | |---|---| | Scaffolding clean architecture | scaffold-clean-arch | | SDLC artifacts contract | sdlc-artifacts-contract | | Semantic versioning / changelog | semantic-versioning-changelog | | In-memory search registry | in-memory-search-registry |

If overlap is found:

1. Drop the new skill if the existing one fully covers the scope
2. Drop the new skill if an imported skill in ai-context/skills/ already covers the scope
3. Narrow the new skill's scope to a specific sub-domain the existing skill omits
4. Document the narrowing in the When to Use section's negative conditions

---

Generation Checklist

Before marking the generated skill as quality-gate ready:

Schema completeness (Tier 1)

• [ ] YAML frontmatter: name (kebab-case) and description fields present
• [ ] description is 1–3 sentences, quotable as a tool description
• [ ] description contains concrete trigger signals (not generic)
• [ ] Problem section: 2–4 sentences, names the failure mode
• [ ] When to Use section: 3–6 specific conditions, at least one negative
• [ ] Core content section: present, title matches category type
• [ ] Examples section: at least 2 scenario-based examples
• [ ] Related Skills section: at least 1 relationship with description
• [ ] All code blocks are complete (no ... as placeholders in runnable code)
• [ ] No placeholder content ({fill in}, TBD, TODO as section content)
• [ ] Naming follows kebab-case conventions
• [ ] Overlap check passed (ecosystem KB tables + project KB imported skills)
• [ ] Authoring pattern chosen (see skill-authoring-patterns); sub-files used only for ecosystem KB skills with ≥5KB verbatim content
• [ ] Skill size ≤15KB, or decomposition/Reference Pattern evaluated if larger

Coherence (Tier 2 — Code Reviewer, if agent skill or orchestrator support skill)

• [ ] When to Use conditions are consistent with description trigger signals
• [ ] Code examples use correct C# / relevant language for the domain
• [ ] All Related Skills references exist in the KB

---

Examples

Example 1 — Procedure skill

Scenario: Team repeatedly makes mistakes wiring Channel<T> producer-consumer patterns. A reusable guide would prevent the pattern from diverging.

Skill ID: channel-producer-consumer Category: Procedure Core section title: ## Implementation Steps

The skill walks through: creating a bounded channel, wiring a producer, wiring a consumer worker, handling back-pressure, and graceful shutdown. Each step has a compilable code snippet.

Example 2 — Decision-guide skill

Scenario: Developers frequently choose the wrong EF Core inheritance strategy (TPH vs TPT vs TPC) without understanding the trade-offs.

Skill ID: ef-inheritance-strategy Category: Decision-guide Core section title: ## Strategy Selection Matrix

The skill provides a decision matrix: number of subtypes × column similarity × query frequency → recommended strategy, with a tie-breaker rule.

Example 3 — Template skill

Scenario: Every new bounded context needs the same boilerplate: one aggregate, one repository interface, one application service interface.

Skill ID: gen-bounded-context Category: Template Core section title: ## Scaffold Template

The skill provides parameterized templates with ${1:EntityName} slots for aggregate, repository interface, and application service interface. Fill instructions precede the template body.

---

Related Skills

• gen-agent — generate a new agent (executes behavior) instead of a knowledge artifact
• skill-authoring-patterns — decision framework for choosing between Inline, Reference, and Few-Shot authoring patterns
• agentic-workflow-patterns — understand the role of skills in the agent pipeline before creating one
• gen-copilot-instructions — generate scoped instruction files that reference skills