Skill Publish#

Publish an AI agent skill to GitHub and multiple skill registries in one workflow.

The overall flow is: GitHub first, then skills.sh and clawhub.ai, with skillsmp.com auto-syncing from GitHub. Skill name and description on all platforms come from the SKILL.md frontmatter, keeping everything consistent with the GitHub repo.

Prerequisites#

Before running this skill, check that the required CLI tools are available. If any are missing, guide the user through installation.

1. git — required. Check with git --version.

2. gh (GitHub CLI) — required for skills.sh publishing. Check with gh --version.

3. gh skill publish extension — required for skills.sh. Check with gh extension list | grep skill.

   • Install: gh extension install skills-sh/skill-publish

4. clawhub CLI — required for clawhub.ai publishing. Check with which clawhub.

   • Install: npm i -g clawhub
   • Login: clawhub login (GitHub OAuth)
   • Verify: clawhub whoami

If a tool is missing, ask the user whether to install it or skip that platform.

Workflow#

Follow these steps in order.

Step 1: Resolve the remote URL#

1. Read references/repo-map.json (relative to this skill's directory). This file maps local project paths to their GitHub URLs.

2. Compare the current working directory against the keys in the mapping.

3. If a mapping is found: Use the stored URL. Tell the user: "Detected repo: "

4. If no mapping is found: Ask the user to provide the GitHub repository URL. Accept formats like:

   • https://github.com/user/repo.git
   • git@github.com:user/repo.git
   • https://github.com/user/repo

Step 2: Check and initialize Git if needed#

Run git status to check if the current directory is a Git repository.

If NOT a Git repository:

1. Run git init
2. Run git add . to stage all files
3. Run git commit -m "Initial commit"
4. Run git remote add origin <URL>
5. Run git branch -M main

If already a Git repository:

1. Check if remote origin exists: git remote get-url origin
   • If the URL differs from what was resolved, ask the user whether to update it
   • If no remote origin exists, run git remote add origin <URL>

Step 3: Handle uncommitted changes#

Check for uncommitted changes with git status --porcelain.

If there are uncommitted changes:

1. Run git diff --cached to see staged changes
2. Run git diff to see unstaged changes
3. Stage all changes: git add .
4. Analyze the staged changes and generate a commit message:
   • Follow conventional commit format: type(scope): brief summary
   • Types: feat, fix, chore, docs, refactor, style, test
   • Title no more than 50 characters
   • Body lists the affected files and what changed
5. Run git commit -m "<generated message>"

If no uncommitted changes: Proceed to push.

Step 4: Push to GitHub#

1. Detect the current branch: git branch --show-current

2. Try normal push: git push -u origin <branch>

3. If the push fails with a connection error (e.g., "Could not connect to server", "Failed to connect", timeout, network unreachable):

   • Run git remote get-url origin to inspect the current URL.

   • If the URL starts with https://, retry up to 3 times.

   • If all 3 HTTPS retries fail, automatically switch to SSH:

     • Convert: https://github.com/user/repo.git → git@github.com:user/repo.git
     • Run git remote set-url origin <ssh-url>
     • Try pushing again.

   • If the remote is already SSH and fails, retry up to 3 times, then report the error.

4. If the push fails for other reasons (e.g., divergent histories):

   • Ask the user: "Push failed. Force push? This may overwrite remote history. (y/n)"
   • If yes: git push -u origin <branch> --force
   • If no: stop and report.

Step 5: Save the GitHub mapping#

Update references/repo-map.json with the current project path and its GitHub URL so future publishes skip the URL prompt.

Step 6: Publish to skills.sh#

skills.sh is a skill registry that auto-discovers skills from GitHub. The gh skill publish extension validates the skill and creates a GitHub release.

1. Check if gh skill publish extension is installed.

   • If not, offer to install: gh extension install skills-sh/skill-publish

2. Read the SKILL.md frontmatter from the current skill directory to get the skill name and description.

3. Run: gh skill publish --slug <skill-name>

   • The --slug should match the name field in SKILL.md frontmatter.
   • If gh skill publish is not available, skip and tell the user: "skills.sh will auto-discover your skill from the GitHub repo. For faster indexing, install the extension with gh extension install skills-sh/skill-publish."

4. If publishing succeeds, report: "Published to skills.sh: https://skills.sh///"

Step 7: Publish to clawhub.ai#

ClawHub is a skill marketplace with CLI-based publishing. It requires authentication via GitHub OAuth.

1. Check if clawhub CLI is installed.

   • If not, offer to install: npm i -g clawhub

2. Check if the user is logged in: clawhub whoami

   • If not logged in, guide the user: clawhub login

3. Read the SKILL.md frontmatter to get the skill name and description.

4. Derive the version from git describe --tags --always or use "1.0.0" for first publish.

5. Run: clawhub skill publish . --slug <skill-name> --name "<skill-name>" --version <version> --changelog "<commit-message>"

   • The --name and description come from SKILL.md frontmatter to stay consistent.

6. If publishing succeeds, report: "Published to clawhub.ai: https://clawhub.ai/skills/"

Step 8: Note about skillsmp.com#

skillsmp.com automatically scrapes GitHub for public repos with SKILL.md files. No manual action is needed. Tell the user: "skillsmp.com will auto-sync from the GitHub repo (may take a few hours)."

Step 9: Confirm success#

Report the final status of all platforms:

text

Publish complete!
  GitHub:   <url> (branch: <branch>, commit: <message>)
  skills.sh: Published / auto-discoverable
  clawhub.ai: Published / skipped
  skillsmp.com: Auto-sync from GitHub

If any platform failed, clearly state which ones succeeded and which need manual follow-up.

Update flow#

When the user wants to update an already-published skill, the workflow is the same — GitHub push first, then re-publish to each platform:

• skills.sh: Re-run gh skill publish to create a new release.
• clawhub.ai: Run clawhub skill publish with an incremented version number. Use git log --oneline <last-tag>..HEAD to generate a changelog from recent commits.
• skillsmp.com: Auto-syncs, no action needed.

Self-Evolution Mechanism#

After each execution of this Skill:

1. Evaluate whether the output achieved the intended goal: pass / fail.
2. If it fails, reflect on the cause of failure and append a "failure case + improvement suggestion" to diary/YYYY-MM-DD.md.
3. If a certain improvement suggestion is repeatedly mentioned in the most recent three executions, refine it into a formal rule and submit a PR to modify this SKILL.md.

Reference files#

• references/repo-map.json — Local path to GitHub URL mappings. Read this first to resolve the remote URL; update it after each successful push.