skills-standards

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 separate file under `src/`:
- `config.ts` — typed environment configuration
- `model.ts` — domain types (readonly, no classes)
...

Now the skill duplicates the entire CMDO definition from backend-scaffolding. When that pattern changes, this copy drifts silently.

GOOD

## Backend Generation
Delegate to the `backend-scaffolding` skill to generate the server component
directory structure and source files. It expects a component name and server
settings from `sdd-settings.yaml`, and produces a ready-to-build `src/` tree.

The reader knows what to pass in, what comes out, and where the responsibility lives — without needing to read backend-scaffolding or duplicating its internals.

Input / Output Schema

Every skill that accepts parameters or produces structured output must define them as colocated JSON Schema files. This keeps schemas machine-readable, validatable, and composable — the output schema of one skill can be validated against the input schema of the next.

File layout

plugin/<layer>/skills/my-skill/     # <layer> = core/ or fullstack-typescript/
├── SKILL.md
└── schemas/
    ├── input.schema.json       # What this skill accepts
    └── output.schema.json      # What this skill produces

Schema files live in a schemas/ subdirectory within the skill's directory. The SKILL.md references them but does not duplicate their contents.

Schema file format

Use JSON Schema Draft 2020-12. Example input.schema.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "my-skill input",
  "description": "Parameters for the skill.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Identifier for the item to process"
    },
    "mode": {
      "type": "string",
      "enum": ["full", "partial", "dry-run"],
      "description": "Processing mode"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Optional labels to attach"
    }
  },
  "required": ["name", "mode"]
}

Example output.schema.json:

{
  "$schema": "htt