blueprint.yaml Reference

The complete field reference for Blueprint package manifests. Every package is defined by a blueprint.yaml file at the root of the package directory.

Ref Format

Packages are identified by a fully-qualified ref string used in blueprint install, in includes lists, and in the lockfile:

@namespace/type/name@version

Segment	Description
@namespace	The org slug that owns the package. The leading `@` is required.
type	One of `knowledge`, `ai-native`, `tools`, `skeletons`, `packages`
name	Lowercase slug. Must not contain `..`, `/`, or `\`.
@version	Semver string (e.g. `1.0.0`). Omit to resolve the latest version.

Example: @blueprint/knowledge/go-best-practices@1.0.0

Top-Level Fields

These fields apply to every package type.

Field	Type	Required	Description
type	enum	yes	Package type. One of `knowledge`, `ai-native`, `tools`, `skeletons`, `packages`.
sub-type	enum	no	Refines the type for `ai-native` and `skeletons` packages. Values: `agent`, `skill`, `command`, `workflow`, `project`, `component`, `module`.
name	string	yes	Lowercase slug identifying the package within its namespace and type. Must not contain `..`, `/`, or `\`.
namespace	string	yes	The org slug that owns this package. Must match the claimed namespace in the registry.
version	string	yes	Semver version string, e.g. `1.0.0`. Stored as a git tag in the registry.
description	string	no	Short, human-readable description shown on the registry package page.
visibility	enum	no	Install access control. Default: `private` (org members only). Set to `public` to allow unauthenticated installs by anyone.

Type-Specific Fields

Each package type uses a different set of additional fields. Only include the section that matches your type.

`packages` — includes

Bundle packages declare a list of sub-packages to install. Sub-packages are identified by their full ref string.

Field	Type	Required	Description
includes.required	list	no	Sub-packages always installed as part of this bundle.
includes.optional	list	no	Sub-packages the user may accept or skip during install.

type: packages
name: sdlc
namespace: blueprint
version: 1.0.0
description: Complete opinionated software development lifecycle
visibility: public

includes:
  required:
    - "@blueprint/knowledge/sdlc-ethos@1.0.0"
    - "@xadk/ai-native/workflows/sdlc-sequences@1.0.0"
    - "@xadk/tools/sdlc-cli@1.0.0"
  optional:
    - "@blueprint/skeletons/go-composable-monorepo@1.0.0"

`skeletons` — variables

Skeleton packages render {{VARIABLE}} placeholders in .tmpl files using values collected from the user at install time.

Field	Type	Required	Description
variables[].name	string	yes	Template variable name. Used as `{{NAME}}` in skeleton files.
variables[].prompt	string	yes	Question shown to the user at install time.
variables[].required	bool	yes	If `true`, install fails if no value is provided and no default is set.
variables[].default	string	no	Value used if the user skips the prompt.

type: skeletons
sub-type: project
name: go-service
namespace: blueprint
version: 1.0.0
description: Production Go microservice with hexagonal architecture
visibility: public

variables:
  - name: PROJECT_NAME
    prompt: "Project name (e.g., acme)"
    required: true
  - name: GO_MODULE
    prompt: "Go module path (e.g., github.com/acme/api)"
    required: true
  - name: DESCRIPTION
    prompt: "Short project description"
    required: false
    default: "A Blueprint Go service"

`tools` — install

Tool packages delegate installation to the native package manager for the chosen method. Blueprint pins the exact version declared in the manifest.

Field	Type	Required	Description
install.method	enum	yes	How the tool is installed. One of `cargo`, `pip`, `npm`, `go`, `binary`, `script`.
install.binary	string	no	Name of the installed binary used to verify a successful install.
install.package	string	no	Package name in the upstream registry (crate name, pip package, npm package, Go module path). Defaults to `name` if omitted.
install.post-install	list	no	Shell commands run after the install completes, e.g. to verify or configure the tool.

type: tools
name: sdlc-cli
namespace: xadk
version: 1.0.0
description: SDLC state machine CLI
visibility: public

install:
  method: cargo
  binary: sdlc
  package: sdlc-cli
  post-install:
    - "sdlc --version"

`knowledge` — knowledge

Knowledge packages install Markdown articles into the project and optionally add them to the CLAUDE.md index so AI assistants can discover them.

Field	Type	Required	Description
knowledge.dest	string	no	Destination path within the project. Default: `.blueprint/knowledge/{name}/`
knowledge.index	bool	no	If `true`, installed files are appended to the CLAUDE.md knowledge index.
knowledge.link-from	string	no	Path of the file to append the knowledge link into (e.g. `CLAUDE.md`).

type: knowledge
name: go-best-practices
namespace: blueprint
version: 1.0.0
description: Go architecture patterns, performance tips, and idioms
visibility: public

knowledge:
  dest: .blueprint/knowledge/go-best-practices/
  index: true
  link-from: CLAUDE.md

`ai-native` — adapters

AI-native packages install agents, skills, commands, and workflows into AI platform directories. Blueprint auto-detects which platforms are present (by checking for .claude/, .opencode/, etc.) and writes to the matching destinations.

Field	Required	Description
adapters.claude-code.dest	no	Write destination for Claude Code (e.g. `.claude/agents/{name}.md`).
adapters.opencode.dest	no	Write destination for OpenCode.
adapters.gemini-cli.dest	no	Write destination for Gemini CLI.
adapters.antigravity.dest	no	Write destination for Antigravity.

type: ai-native
sub-type: agent
name: primary-developer
namespace: xadk
version: 1.0.0
description: Senior engineer persona with deep domain context
visibility: public

adapters:
  claude-code:
    dest: .claude/agents/primary-developer.md
  opencode:
    dest: .opencode/agents/primary-developer.md
  gemini-cli:
    dest: .gemini/agents/primary-developer.json
  antigravity:
    dest: .antigravity/primary-developer.json

Registry-Managed Fields

The following fields are written by the registry after a package is published. Publishers should not set these in their blueprint.yaml — they will be overwritten.

Field	Description
file-manifest	Populated at publish time. A list of all files in the package, each with a `path`, `sha256`, and `size`. Used by the CLI for pre-install disclosure and integrity verification.
disclosure	Populated after the security scan runs. Contains `security-status` (`safe`, `warning`, `blocked`, or `unscanned`), `scanned-at`, `scanner-version`, and `report-url`. Packages are available immediately after publish with `unscanned` status.

Next steps

Getting Started →Browse packages →View docs →

blueprint.yaml Reference

Ref Format

Top-Level Fields

Type-Specific Fields

packages — includes

skeletons — variables

tools — install

knowledge — knowledge