GH-SKILL-PUBLISH(1) GitHub CLI manual GH-SKILL-PUBLISH(1)

# [NAME](#NAME)

gh-skill-publish - Validate and publish skills to a GitHub repository (preview)

# [SYNOPSIS](#SYNOPSIS)

**gh skill publish \[<directory>] \[flags]**

# [DESCRIPTION](#DESCRIPTION)

Validate a local repository's skills against the Agent Skills specification and publish them by creating a GitHub release.

Skills are discovered using the same conventions as install:

- **skills/\*/SKILL.md**
- **skills/{scope}/\*/SKILL.md**
- **\*/SKILL.md** (root-level)
- **plugins/{scope}/skills/\*/SKILL.md**

Validation checks include:

- Skill names match the strict agentskills.io naming rules
- Each skill name matches its directory name
- Required frontmatter fields (name, description) are present
- allowed-tools is a string, not an array
- Install metadata (**metadata.github-\***) is stripped if present

After validation passes, publish will interactively guide you through:

- Adding the **agent-skills** topic to the repository
- Choosing a version tag (semver recommended)
- Creating a GitHub release with auto-generated notes

Use **--dry-run** to validate without publishing. Use **--tag** to publish non-interactively with a specific tag. Use **--fix** to automatically strip install metadata from committed files without publishing. Review and commit the changes, then run publish again.

# [OPTIONS](#OPTIONS)

[**--dry-run**](#dry_run)

Validate without publishing

[**--fix**](#fix)

Auto-fix issues where possible without publishing (e.g. strip install metadata)

[**--tag** **<string>**](#tag)

Version tag for the release (e.g. v1.0.0)

# [EXIT CODES](#EXIT_CODES)

0: Successful execution

1: Error

2: Command canceled

4: Authentication required

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information.

# [EXAMPLE](#EXAMPLE)

```
# Validate and publish interactively
$ gh skill publish
# Publish with a specific tag (non-interactive)
$ gh skill publish --tag v1.0.0
# Validate only (no publish)
$ gh skill publish --dry-run
# Strip install metadata without publishing
$ gh skill publish --fix
```

# [SEE ALSO](#SEE_ALSO)

[**gh-skill(1)**](/man/os/gh/gh-skill.1)

Oct 2026

---

Document: gh-skill-publish(1) from gh 2.103.0-r0 (Chainguard OS)
Source: https://github.com/cli/cli