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



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:

       o skills/*/SKILL.md

       o skills/{scope}/*/SKILL.md

       o */SKILL.md (root-level)

       o plugins/{scope}/skills/*/SKILL.md


       Validation checks include:

       o Skill names match the strict agentskills.io naming rules

       o Each skill name matches its directory name

       o Required frontmatter fields (name, description) are present

       o allowed-tools is a string, not an array

       o Install metadata (metadata.github-*) is stripped if present


       After validation passes, publish will interactively guide you through:

       o Adding the agent-skills topic to the repository

       o Choosing a version tag (semver recommended)

       o 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)

                                   Sep 2026                GH-SKILL-PUBLISH(1)