Creating Presets

Relevant source files

• .github/CODEOWNERS
• .github/ISSUE_TEMPLATE/extension_submission.yml
• .github/ISSUE_TEMPLATE/preset_submission.yml
• .github/workflows/add-community-extension.lock.yml
• .github/workflows/add-community-extension.md
• .github/workflows/add-community-preset.lock.yml
• .github/workflows/add-community-preset.md
• .github/workflows/catalog-assign.yml
• CONTRIBUTING.md
• docs/community/presets.md
• presets/PUBLISHING.md
• presets/catalog.community.json
• presets/catalog.json
• presets/lean/README.md
• presets/lean/commands/speckit.constitution.md
• presets/lean/commands/speckit.implement.md
• presets/lean/commands/speckit.plan.md
• presets/lean/commands/speckit.specify.md
• presets/lean/commands/speckit.tasks.md
• presets/lean/preset.yml
• spec-driven.md
• tests/test_github_workflows.py
• tests/test_shared_infra_integrity.py

This page explains how to create custom preset packages for the Spec Kit preset system. A preset is a distributable package containing template files, command definitions, or script overrides that customize the behavior of a Spec Kit project. Presets enable organizations to standardize workflows, enforce compliance requirements, or adapt Spec-Driven Development to specific domains.

For information about installing and using presets, see 8.1 Using Presets. For details on how template resolution works, see 8.2 Template Resolution.

---

Preset Package Structure

A preset package is a directory (or a ZIP archive) containing a preset.yml manifest and one or more artifact files. The directory structure follows this pattern:

Key constraints:

• preset.yml is mandatory and must be in the root directory presets/PUBLISHING.md37
• Artifact files are organized by type (templates/, commands/, scripts/) presets/PUBLISHING.md31-49
• Command names must follow the speckit.{ext}.{cmd} pattern for extension overrides or speckit.{cmd} for core overrides presets/PUBLISHING.md93
• The id must be lowercase with hyphens only presets/PUBLISHING.md87

Sources: presets/PUBLISHING.md31-49 presets/PUBLISHING.md87-93

---

Preset Manifest Format

The preset.yml file uses YAML format and defines the metadata, requirements, and provided templates.

Manifest Fields

Field	Type	Required	Description
schema_version	string	Yes	Must be "1.0" presets/PUBLISHING.md58
preset.id	string	Yes	Unique lowercase-hyphenated ID presets/PUBLISHING.md61
preset.version	string	Yes	Semantic version string (X.Y.Z) presets/PUBLISHING.md63
requires.speckit_version	string	Yes	Minimum Spec Kit version required presets/PUBLISHING.md70
provides.templates	list	Yes	List of template/command objects presets/PUBLISHING.md72-79

Sources: presets/PUBLISHING.md57-83

---

Artifact Types and Composition

Presets support overrides for templates, commands, and scripts. Unlike simple overrides, presets support composition strategies that determine how content is merged with lower-priority layers.

1. Template Artifacts (type: "template")

These override the document scaffolds used to generate files like spec.md or plan.md.

• Resolution: Handled via a priority stack where presets sit above extensions but below local overrides presets/PUBLISHING.md102-103
• Targets: Core templates (e.g., spec-template) or extension templates presets/PUBLISHING.md74-78

2. Command Artifacts (type: "command")

These override the instructions (slash commands) given to AI agents.

• Registration: Applied at install time. The CLI writes these into agent-specific directories (e.g., .claude/commands/, .github/agents/) presets/PUBLISHING.md118-126
• Format Handling: The system automatically adapts the command source to the required format (Markdown, TOML, or YAML) depending on the target agent presets/PUBLISHING.md118-126

3. Script Artifacts

Allows presets to provide alternative versions or wrappers for core workflow scripts found in .specify/scripts/ presets/PUBLISHING.md42

Sources: presets/PUBLISHING.md31-49 presets/PUBLISHING.md72-83 presets/PUBLISHING.md118-126

---

Implementation Architecture

The following diagrams illustrate the relationship between the Natural Language concepts (Presets, Commands) and the code entities that implement them.

Preset Resolution and Priority Flow

This diagram shows how the system resolves template content across different layers.

Sources: presets/PUBLISHING.md99-113 presets/catalog.community.json5-23

Command Registration Logic

This diagram bridges the concept of "Installing a Command" to the actual file operations performed for AI agents.

Sources: presets/PUBLISHING.md115-126 presets/PUBLISHING.md144-149

---

Priority and Resolution

When multiple presets provide the same template, the system uses a priority-based stack.

• Local Overrides: Highest priority; stored in .specify/templates/overrides/.
• Presets: Mid-level priority; resolve based on installation order or specific priority configuration.
• Extensions: Lower priority than presets.
• Core Defaults: Lowest priority; the base templates provided by Spec Kit.

Sources: presets/PUBLISHING.md99-113

---

Creating a Preset: Step-by-Step

1. Scaffold the Directory

Create a new directory containing a preset.yml, a README.md, and a LICENSE presets/PUBLISHING.md33-49

2. Configure the Manifest

Edit preset.yml. Ensure the id is unique and follows the lowercase-hyphenated convention presets/PUBLISHING.md61 Define the requires section to specify the minimum Spec Kit version presets/PUBLISHING.md69-70

3. Implement Overrides

• Templates: Place Markdown files in templates/ and map them in the provides section presets/PUBLISHING.md72-79
• Commands: Place in commands/. Use the speckit.{command}.md naming convention presets/PUBLISHING.md47-48

4. Local Testing

Install the preset from your local directory to verify it works as expected:

Verify resolution:

Sources: presets/PUBLISHING.md96-113

---

Catalog Submission

To make a preset discoverable via specify preset search, it must be added to the community catalog.

Submission Requirements

1. Valid Manifest: Must have a valid preset.yml presets/PUBLISHING.md20
2. Documentation: A README.md containing a valid specify preset add command presets/PUBLISHING.md22
3. License: An open-source license file presets/PUBLISHING.md23
4. Release: A GitHub release with a version tag (e.g., v1.0.0) presets/PUBLISHING.md128-136

Automated Validation Workflow

Submissions are processed via the Add Community Preset from Issue Submission workflow .github/workflows/add-community-preset.md46-50 This agent performs the following checks:

• ID/Version Format: Validates regex ^[a-z][a-z0-9-]*$ and semver .github/workflows/add-community-preset.md94-100
• Repository Integrity: Checks for preset.yml and LICENSE .github/workflows/add-community-preset.md101-105
• README Validation: Ensures the README is on GitHub and contains an installation command .github/workflows/add-community-preset.md110-151

Once validated, the agent automatically updates presets/catalog.community.json and docs/community/presets.md .github/workflows/add-community-preset.md183-210

Sources: presets/PUBLISHING.md1-216 .github/workflows/add-community-preset.md1-210 presets/catalog.community.json1-37