/skills-standards

name: skills-standards
description: Standards for authoring SDD plugin skills — frontmatter, self-containment, and input/output schemas.

Skills Standards

Standards for every skill in the plugin. Apply when creating or reviewing plugin skills.

---

Scope

This standard applies to skills shipped with the SDD plugin — all `SKILL.md` files found recursively under `plugin/core/skills/` and `plugin/fullstack-typescript/skills/`. It does not apply to the repo's own `.claude/skills/`.

---

Frontmatter

Every `SKILL.md` must start with YAML frontmatter. The following fields are supported:

---
name: my-skill              # OPTIONAL — kebab-case, uses directory name if omitted
description: >              # RECOMMENDED — what it does + what it needs/produces
  Discover required technical components through targeted questions
  based on classified requirements. Accepts classified requirements
  and produces a component list with types, names, and rationale.
user-invocable: false        # OPTIONAL — true if user can invoke via /command (default: true)
model: opus                  # OPTIONAL — model to use when skill is active
disable-model-invocation: true  # OPTIONAL — prevent Claude from auto-loading (default: false)
---

Required Fields

Only `description` is recommended. All other fields are optional.

Supported Fields

| Field | Type | Default | Rule | |-------|------|---------|------| | `name` | `string` | Directory name | kebab-case, matches parent directory name if specified | | `description` | `string` | First paragraph | 1-3 sentences. First sentence: what the skill does. Remaining sentences (optional): what it accepts/produces, key constraints, or disambiguation from similar skills. Never reference where or when the skill is used — the skill doesn't know its callers. The model uses this to decide whether to load the skill, so include enough signal for accurate selection. | | `user-invocable` | `boolean` | `true` | `true` if the user invokes it via `/skill-name`; `false` for internal skills invoked by the plugin workflow or other skills | | `model` | `string` | Inherits session model | Model to use when this skill is active. Options: `opus`, `sonnet`, `haiku`, `inherit` | | `disable-model-invocation` | `boolean` | `false` | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually. | | `argument-hint` | `string` | None | Hint shown during autocomplete to indicate expected arguments (e.g., `[issue-number]`, `[filename] [format]`) | | `allowed-tools` | `string` | None | Comma-separated list of tools Claude can use without permission when this skill is active | | `context` | `string` | None | Set to `fork` to run in a forked subagent context | | `agent` | `string` | `general-purpose` | Which subagent type to use when `context: fork` is set | | `hooks` | `object` | None | Hooks scoped to this skill's lifecycle |

**For SDD plugin skills, only use frontmatter fields that are necessary for the skill's functionality.** Keep frontmatter minimal and prefer documentation in the skill body.

---

Self-Containment

The less a skill assumes about its environment, the more portable, reusable, and maintainable it is. A skill that depends on implicit knowledge from other skills is fragile — renaming, restructuring, or removing a dependency silently breaks it. A self-contained skill can be moved, composed differently, or understood in isolation.

Each skill must be fully understandable on its own. An LLM reading a single skill should never need to read another skill to understand what this skill requires it to do.

Rules

1. **Delegate clearly** — When referencing another skill, state what you expect it to do (the contract), not how it works internally. The reader should understand the *role* of the delegated skill without reading it. 2. **Don't duplicate** — Never copy definitions, patterns, or rules from another skill into yours. Duplication creates drift and bloats skills with out-of-context information. If a concept is owned by another skill, delegate to it. 3. **No cross-skill file references** — Never reference or read files inside another skill's directory. A skill's internal files (templates, schemas, references) are private to that skill. If two skills need the same template or data, either consolidate them into one skill or extract the shared content into each skill's own directory. Cross-skill file references create hidden coupling that breaks when skills are moved, renamed, or restructured. 4. **No environment assumptions** — Do not assume a specific directory structure, tool version, or runtime context unless the skill explicitly documents it. If the skill requires a file to exist or a tool to be available, state that as a precondition. 5. **Define your own terms** — If the skill introduces domain-specific vocabulary, define it on first use. Don't define terms that belong to other skills — delegate instead. 6. **Complete examples** — Every example must be understandable without external context. Include the data shapes, field names, and structure needed to make the example self-contained. 7. **Plugin boundary** — Plugin skills (`plugin/core/skills/` and `plugin/fullstack-typescript/skills/`) have no runtime access to anything outside `plugin/`. Never reference `.claude/`, `.tasks/`, or root-level files from within a plugin skill.

Cross-references

A skill references another skill by describing what it expects from it — the delegation contract. This is the only form of cross-reference needed.

BAD

## Backend Generation
Follow the `backend-scaffolding` skill for CMDO structure.

The reader doesn't know what `backend-scaffolding` will produce or what role it plays in this skill's workflow.

ALSO BAD

## Backend Generation
Generate backend components using the CMDO pattern (Config, Model, DAL, Operator)
with a Controller entry point. Each layer is a se