Text of github.github.com › gh-aw › reference › aw-yml-package-manifest as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Package Manifest (aw.yml) | GitHub Agentic Workflows

Skip to main content 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 Section titled “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 Section titled “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 Section titled “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 Section titled “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 Section titled “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 Section titled “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 Section titled “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 destination : .github/workflows/controller.yml kind : action-workflow - source : payload/extra-workflows/* destination : .github/workflows/ With a nested package reference such as owner/repo/factory , the files above are fetched from factory/payload/workflows/ and installed to .github/workflows/ .

Because the sources live outside .github/workflows/ in the distribution repository, they never run there. The optional kind field is either agentic-workflow ( .md ) or action-workflow ( .yml ) and must match the source extension. Mappings are rejected when source or destination is absolute, contains .. , points at a symbolic link, uses an unsupported extension (or .lock.yml ), changes the file extension between source and destination, or targets anything other than a direct child of .github/workflows/ .

A wildcard mapping is the exception: it targets the .github/workflows/ folder, then preserves each matching source filename. Two entries installing to the same destination are rejected before any file is written. gh aw add , gh aw add-wizard , and gh aw update all use these same mapping rules. String entries can also install skill directories under skills/ or .github/skills/ when they contain SKILL.md , and agent Markdown files under agents/ or .github/agents/ .

If files is omitted, or no valid entries remain after filtering, gh aw add discovers installable markdown files under: workflows/ .github/workflows/ If no installable workflow files are resolved, validation fails. Resources Section titled “Resources” The resources field copies repository assets as-is without executing them during installation. Each entry maps a package-relative source to a repository-relative destination .

Supported destinations are: Direct children of .github/ISSUE_TEMPLATE/ with a .yml or .yaml extension .github/CODEOWNERS Files under .github/aw/ .mjs and .cjs helper scripts under .github/workflows/shared/ Resource destinations must be unique, including case-insensitive comparisons. Path trave

The rest of this page is on the live site.