Package Manifest (aw.yml)

Use aw.yml to describe an installable agentic workflow package. gh aw add uses this manifest when installing packages, and gh aw compile validates repository-root manifests before compilation.

For the normative file-format definition, see the Package Management (Spec).

Package reference formats

Repository references support two forms:

OWNER/REPO
OWNER/REPO/PATH/TO/PACKAGE

The package root is the folder that contains aw.yml.

Fields

Field	Type	Required	Notes
`manifest-version`	string	No	Current supported value: `"1"`. Defaults to `"1"` when omitted.
`min-version`	string	No	Minimum compatible `gh aw` version in `vMAJOR.minor.patch` form, such as `v0.38.0`.
`name`	string	Yes	Human-readable package name. Must be non-empty after trimming whitespace.
`emoji`	string	No	Optional package emoji for display in package metadata.
`icon`	string	No	Optional package icon: an emoji, a GitHub primer octicon name in `:name:` format (e.g. `:check-circle:`), or a package resource path to an SVG file.
`description`	string	No	Optional package description. `gh aw add` warns when it exceeds 255 characters.
`private`	boolean	No	Marks the package as unavailable for installation. Defaults to `false`; `gh aw add` refuses packages set to `true`.
`experimental`	boolean	No	Marks the package as experimental. Defaults to `false`; `gh aw add` displays a warning when set to `true`.
`files`	array of strings	No	Deprecated; use `includes`. Package-root-relative paths. Agentic markdown workflows under `workflows/` or `.github/workflows/`; raw GitHub Actions YAML (`.yml`) is also accepted as direct children of `.github/workflows/`.
`includes`	array	No	Installable entries, or paths to other `aw.yml` manifests whose installable files are included recursively. Each entry is either a path string (same rules as `files`, plus skill and agent paths), a path ending in `/*` that matches supported direct children, or a source-to-destination mapping.
`resources`	array	No	Repository assets copied from package-relative `source` paths to allowlisted repository-relative `destination` paths.
`config`	array	No	Experimental ordered repository setup actions applied by `gh aw add-wizard`.

Repository labels

Use a repo-label config action to create a repository label or reconcile an existing label’s description and color:

config:
  - type: repo-label
    name: automation
    description: Managed by an agentic workflow
    color: 1f6feb

The name must be non-empty and at most 50 characters. The description must be non-empty and at most 100 characters. color must be a six-character hexadecimal value without a leading #.

Imported manifests

Use includes entries naming aw.yml files to compose a package from manifests in the same repository:

name: Central Agentic Ops
includes:
  - activity/aw.yml
  - ambient-context/aw.yml
  - dashboard/aw.yml

These paths are resolved relative to the manifest that declares them and must name an aw.yml file within the repository. A nested package may import a manifest above it (for example ../aw.yml) as long as that manifest does not import the nested package back. Imports are recursive. The imported manifests’ workflows, resources, skills, and agents are combined into one install list; metadata and config continue to come from the top-level manifest.

An entry that resolves to the manifest declaring it (for example ./aw.yml inside child/aw.yml) is ignored with a warning, because imports resolve relative to the manifest that declares them. Imports that reach above the repository root are rejected.

gh aw rejects import cycles and any files that would install to the same destination, including case-insensitive destination clashes. A manifest that only declares imports does not auto-discover workflows from its own directory.

Installable workflows

If files is present, valid entries become the install bundle. Two entry kinds are supported:

Agentic workflow markdown — paths ending in .md under workflows/ or .github/workflows/. gh aw add compiles these to lock files and fetches their dependencies.
Raw GitHub Actions YAML — paths ending in .yml (but not .lock.yml) that are direct children of .github/workflows/. gh aw add copies these verbatim to .github/workflows/<name>.yml with no frontmatter processing, no dependency fetch, and no compilation. Nested subdirectories under .github/workflows/ and .yml files under workflows/ are not accepted.

Path resolution rules

A string entry that starts with .github/ is resolved relative to the consuming repository root, even inside a nested package. For example, .github/workflows/nightly.md in factory/aw.yml refers to the repository-root file, not to factory/.github/workflows/nightly.md.
Every other string entry (such as workflows/review.md) is resolved relative to the package root.
A string entry may end in a single /* wildcard (such as workflows/*) to include supported direct children of that directory. The wildcard does not recurse, and * is not supported in any other position. Matches are filtered by the same workflow, skill, and agent path rules as explicit entries.
A mapping entry always resolves source relative to the package root and destination relative to the consuming repository root.
A mapping source may end in /*. For wildcard mappings, destination must be the .github/workflows/ folder, and each matching file keeps its source filename.

Source-to-destination mappings

Use mapping entries to keep workflow assets inert in the distribution repository while still installing them into the consuming repository’s .github/workflows/:

name: Factory
includes:
  - source: payload/workflows/reviewer.md
    destination: .github/workflows/reviewer.md
    kind: agentic-workflow
  - source: payload/workflows/controller.yml