---
name: "gh-skill-publish"
section: "1"
platform: "linux"
package: "github-cli"
version: "2.102.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gh-skill-publish"
---

# gh-skill-publish(1)

Validate and publish skills to a GitHub repository (preview)

## NAME

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

## SYNOPSIS

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

## 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

- **--dry-run**

  Validate without publishing

- **--fix**

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

- **--tag** **\<string\>**

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

## 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

```
# 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

**[gh-skill(1)](/gh-skill/1.md)**