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: \x3CURL>"
4. If no mapping is found: Ask the user to provide the GitHub repository URL. Accept formats like:
   • https://github.com/user/repo.git
   • [email protected]: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 \x3CURL>
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 \x3CURL>

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 "\x3Cgenerated 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 \x3Cbranch>
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 → [email protected]:user/repo.git
     • Run git remote set-url origin \x3Cssh-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 \x3Cbranch> --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 \x3Cskill-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/\x3Cowner>/\x3Crepo>/\x3Cskill-name>"

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 \x3Cskill-name> --name "\x3Cskill-name>" --version \x3Cversion> --changelog "\x3Ccommit-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/\x3Cskill-name>"

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:

Publish complete!
  GitHub:   \x3Curl> (branch: \x3Cbranch>, commit: \x3Cmessage>)
  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 \x3Clast-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.