{ "name": "skillhub-publish", "description": "Publish new skills or update existing skills to Alan's Skill Hub. Covers adding, updating, and removing skills via git or GitHub API, including index.json schema and cache invalidation.", "path": "skillhub-publish", "category": "meta", "tags": [ "meta", "publish", "deploy", "git", "github" ], "author": "alanzeng", "version": "1.0.0", "source": "custom", "files": [ "SKILL.md" ], "install": "npx -y skills add https://skill.alanzeng.com --skill skillhub-publish --yes", "raw_url": "https://skill.alanzeng.com/skills/skillhub-publish/SKILL.md", "github_url": "https://github.com/alanzeng423/skill-hub/tree/main/skills/skillhub-publish", "body": "# Skill Hub Publisher\n\nThis skill teaches you how to publish (add, update, or remove) skills to/from Alan's Skill Hub hosted at `https://skill.alanzeng.com`.\n\n## Architecture\n\nThe hub is a Cloudflare Worker that reads skill metadata from `skills/index.json` and skill content from `skills//SKILL.md` in the GitHub repo `alanzeng423/skill-hub` (branch `main`). The Worker caches content in KV for 5 minutes. After pushing to GitHub, changes appear within ~5 minutes.\n\n**To publish, you commit files to GitHub.** There are two methods depending on your environment.\n\n## Prerequisites\n\n- You must have `gh` CLI authenticated, OR be working in a local clone of the repo with git push access.\n- The repo is: `https://github.com/alanzeng423/skill-hub`\n- Branch: `main`\n- Skills live under `skills/` directory; registry is `skills/index.json`.\n\n## Method 1: Working in a local clone (preferred when repo is checked out)\n\nThe local repo path is typically `/Users/bytedance/Code/skill-hub` on the author's machine.\n\n### Add a new skill\n\n1. **Create the SKILL.md file** at `skills//SKILL.md`. It MUST start with YAML frontmatter:\n\n```markdown\n---\nname: \ndescription: \n---\n\n# \n\n\n```\n\n2. **Add supporting files** (optional): scripts, templates, examples — place them alongside SKILL.md in `skills//`.\n\n3. **Update `skills/index.json`**:\n - If the skill belongs to an existing category, add an entry to the `skills` array.\n - If adding a new category, add it to the `categories` array first.\n - Set `updated_at` to the current ISO date (YYYY-MM-DD).\n \n Skill entry schema:\n ```json\n {\n \"name\": \"\",\n \"description\": \"\",\n \"path\": \"\",\n \"category\": \"\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"author\": \"\",\n \"version\": \"1.0.0\",\n \"source\": \"custom | upstream | forked\",\n \"upstream_url\": \"\"\n }\n ```\n\n4. **Commit and push**:\n ```bash\n cd /Users/bytedance/Code/skill-hub\n git add skills// skills/index.json\n git commit -m \"add: skill\"\n git push origin main\n ```\n\n5. **Invalidate cache** (optional, for immediate effect):\n ```bash\n npx wrangler kv key delete hub:index --remote\n ```\n\n### Update an existing skill\n\n1. Edit `skills//SKILL.md` or supporting files.\n2. If metadata changed (description, tags, version, category), update `skills/index.json` accordingly.\n3. Bump `version` following semver (patch for fixes, minor for additions, major for breaking changes).\n4. Commit, push, optionally clear KV cache.\n\n### Remove a skill\n\n1. Delete `skills//` directory.\n2. Remove the entry from `skills/index.json`.\n3. Commit, push, clear KV cache.\n\n## Method 2: Using GitHub API via `gh` (no local clone needed)\n\nIf you don't have a local checkout, use `gh api` or `gh repo` commands to create/update files directly via GitHub API.\n\n### Create SKILL.md via API\n\n```bash\n# Read the current index.json first\ngh api repos/alanzeng423/skill-hub/contents/skills/index.json -q .content | base64 -d > /tmp/current-index.json\n\n# Create the SKILL.md file (base64 encoded)\ngh api repos/alanzeng423/skill-hub/contents/skills//SKILL.md \\\n -X PUT \\\n -f message=\"add: skill\" \\\n -f content=\"$(base64 -i /path/to/SKILL.md)\" \\\n -f branch=main\n\n# Update index.json - add the new skill entry, then:\ngh api repos/alanzeng423/skill-hub/contents/skills/index.json \\\n -X PUT \\\n -f message=\"add: register in index\" \\\n -f content=\"$(base64 -i /tmp/updated-index.json)\" \\\n -f sha=\"$(gh api repos/alanzeng423/skill-hub/contents/skills/index.json -q .sha)\" \\\n -f branch=main\n```\n\n## Category Reference\n\nExisting categories (use one of these unless adding a new one):\n\n| id | name | icon |\n|---|---|---|\n| devops | DevOps & Deployment | 🚀 |\n| cloudflare | Cloudflare | ⚡ |\n| feishu | Feishu / Lark | 🐦 |\n| ai | AI & LLM | 🤖 |\n| frontend | Frontend | 🎨 |\n| backend | Backend | ⚙️ |\n| productivity | Productivity | 📋 |\n| security | Security | 🔒 |\n| meta | Meta | 📦 |\n| other | Other | 📌 |\n\n## Source Types\n\n- **custom** — Original skill built by alanzeng or specifically for this hub\n- **upstream** — Unmodified open-source skill mirrored for convenience (must include `upstream_url`)\n- **forked** — Open-source skill with personalized modifications (must include `upstream_url`)\n\n## After Publishing\n\n1. Wait up to 5 minutes for KV cache to expire, or manually clear `hub:index` key.\n2. Verify at `https://skill.alanzeng.com` — the new skill should appear in the list.\n3. Verify the skill page renders correctly: `https://skill.alanzeng.com/skills/`.\n4. Verify the API: `curl https://skill.alanzeng.com/api/skills/`.\n5. Test installation: `npx -y skills add skill.alanzeng.com --skill --yes`.\n\n## Worker Deployment\n\nThe Worker source (`src/index.ts` and `wrangler.toml`) also lives in the same repo. If you need to change the Worker logic (not just skill content), deploy with:\n\n```bash\ncd /Users/bytedance/Code/skill-hub\nnpx wrangler deploy\n```\n\nAfter deploying the Worker, clear KV cache so fresh content is fetched.\n\n## Important Notes\n\n- The `gh` CLI must be authenticated as `alanzeng423` (the repo owner).\n- Never commit secrets, tokens, or credentials into the skills or repo.\n- Skill files (SKILL.md, scripts, templates) are public — do not include private information.\n- Keep SKILL.md concise and actionable. Frontmatter `name` and `description` are required.\n- Tags help agents discover skills via search — include 2-5 relevant tags.", "frontmatter": { "name": "skillhub-publish", "description": "Publish new skills or update existing skills to Alan's Skill Hub at skill.alanzeng.com. Use this skill whenever you need to add, update, or remove a skill on the hub. The hub is backed by GitHub repo alanzeng423/skill-hub; publishing means committing SKILL.md files and updating index.json on the main branch." } }