Text of github.github.com › gh-aw › specs › repository-package-manifest-specification 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 Management (Spec) | GitHub Agentic Workflows

Skip to main content Package Management (Spec) aw.yml Repository Package Manifest Specification Section titled “aw.yml Repository Package Manifest Specification” Version : 0.3.0 Status : Draft Abstract Section titled “Abstract” This specification defines the aw.yml repository package manifest format used by gh aw to identify, validate, and install repository packages. 1. Introduction Section titled “1. Introduction” The aw.yml manifest describes an installable Agentic Workflow package located either at a repository root or within a nested package folder.

Package references use one of these forms: owner/repo owner/repo/path/to/package The package root is the directory containing aw.yml . 2. Conformance Section titled “2. Conformance” The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119. 3. Manifest location and naming Section titled “3. Manifest location and naming” The canonical manifest filename is aw.yml . 4.

Manifest format Section titled “4. Manifest format” The manifest document MUST be a YAML mapping. Unknown top-level fields MUST be rejected. 4.1 Fields Section titled “4.1 Fields” Field Type Required Meaning manifest-version string No Manifest format version. Defaults to "1" . min-version string No Minimum supported gh-aw version. name string Yes Human-readable package name. emoji string No Optional package emoji for display in package metadata. icon string No Optional package icon: an emoji, a GitHub primer octicon name ( :...: ), or an SVG resource path. description string No Human-readable package description. license string No SPDX license identifier or license name for the package. private boolean No Whether the package is unavailable for installation.

Defaults to false . experimental boolean No Whether the package is experimental. Defaults to false . imports array of strings No Paths to package manifests included recursively in the install set. files array of strings No Deprecated. Explicit installable workflow file list. Use includes instead. includes array of strings or mappings No Explicit installable package entries. String entries use path conventions; mapping entries declare an explicit source-to-destination install path. resources array of mappings No Declarative repository assets copied as-is to allowlisted destinations. config array of mappings No Ordered repository setup actions applied by the interactive installer.

4.2 manifest-version Section titled “4.2 manifest-version” If omitted, manifest-version defaults to "1" . For this version of the format, the only valid value is "1" . 4.3 min-version Section titled “4.3 min-version” If present, min-version MUST use the exact vMAJOR.minor.patch form, such as: v1.2.3 If the running compiler version is lower than min-version , validation MUST fail. 4.4 name Section titled “4.4 name” name MUST be present and MUST be a non-empty string after trimming surrounding whitespace.

4.5 emoji Section titled “4.5 emoji” If present, emoji MUST be a string. 4.5.1 icon Section titled “4.5.1 icon” If present, icon MUST be a non-empty string that matches one of the following formats: Emoji : A single or sequence of Unicode emoji characters. GitHub Primer Octicon : A GitHub Primer octicon name enclosed in colons using :name: format (for example, :check-circle: ). SVG Package Resource : A path to an .svg file that is declared as a package resource in the resources section of aw.yml .

4.6 description Section titled “4.6 description” If present, description MUST be a string. Implementations SHOULD warn if description exceeds 255 characters. 4.7 license Section titled “4.7 license” If present, license MUST be a string. Use an SPDX license identifier such as MIT or Apache-2.0 , or a license name. Non-string values MUST be rejected. 4.8 private Section titled “4.8 private” If omitted, private defaults to false .

When private is true , gh aw add MUST refuse to install the package. 4.9 experimental Section titled “4.9 experimental” If omitted, experimental defaults to false . When experimental is true , gh aw add MUST warn before installing the package. 4.10 files Section titled “4.10 files” If present, files MUST be an array of strings. Each entry MUST be resolved relative to the package root and MUST match one of the following kinds: Agentic workflow markdown — the path MUST end in .md (case-insensitive) and MUST begin with either workflows/ or .github/workflows/ .

Raw GitHub Actions YAML — the path MUST end in .yml (case-insensitive) but MUST NOT end in .lock.yml . It MUST be a direct child of .github/workflows/ (no nested subdirectories) and MUST NOT appear under workflows/ . Duplicate entries SHOULD be ignored after normalization. Path-traversal safety : Each entry in files MUST NOT contain a path-traversal sequence. Specifically, any entry that contains ../ (or ..\ on Windows-style paths), begins with ../ , or resolves to a path outside the package root after normalization MUST be rejected with a validation error.

Implementations MUST NOT follow symlinks that would escape the package root during file resolution. This rule applies regardless of the number of traversal components in the path (e.g., ../../etc/passwd and workflows/../../hidden are both prohibited). 4.10.1 imports Section titled “4.10.1 imports” If present, imports MUST be an array of strings. Each entry MUST resolve relative to the manifest containing it, MUST name an aw.yml file, and MUST remain within the repository root after normalization.

An entry MAY resolve above the package being installed, so a nested package MAY import a manifest closer to the repository root (for example ../aw.yml ). Absolute paths and paths that escape the repository root MUST be rejected. Imports are recursive. Implementations MUST detect import cycles and report the manifest path chain forming the cycle. An entry that resolves to the manifest declaring it (for example ./aw.yml ) is a self-import; implementations MUST ignore it with a warning rather than reporting a cycle.

Each manifest MUST be parsed and validated before its package assets are added to a unified install list. Imported workflows, resources, skills, and agents MUST retain paths relative to the directory containing their manifest. Top-level package metadata and config MUST NOT be replaced by imported manifest values. The unified install list MUST be checked before installation. Two files that resolve to the same case-insensitive destination MUST cause resolution to fail.

A manifest that declares imports but no direct installable files MUST NOT trigger workflow auto-discovery in its own directory. 4.11 includes Section titled “4.11 includes” If present, includes MUST be an array whose entries are either strings or mappings. String entries follow the same rules as files (§4.10), with one special case that MUST be preserved for backward compatibility: a string entry beginning with .github/ is resolved relative to the consuming repository root , not relative to the package root, even for nested packages.

All other string entries (for example workflows/review.md ) are resolved relative to the package root. String entries MAY use one wildcard as their final path segment (for example, workflows/* ). The wildcard MUST be exactly * , MUST be preceded by / , and MUST NOT appear elsewhere in the path. It matches supported direct children of the named directory and MUST NOT recurse into nested directories. Implementations MUST apply the same workflow, skill, and agent path validation used for explicit string entries to every match, MUST ignore unsupported matches, and MUST preserve deterministic lexical ordering.

A .github/ wildcard retains the repository-root-relative behavior described above. Mapping entries declare an explicit source-to-destination install mapping and MUST contain: Key Type Required Meaning source string Yes Path of the file to install, always resolved rela

The rest of this page is on the live site.