{"id":48227044,"url":"https://github.com/wan-huiyan/publish-skill","last_synced_at":"2026-04-04T19:24:22.999Z","repository":{"id":345757182,"uuid":"1187211369","full_name":"wan-huiyan/publish-skill","owner":"wan-huiyan","description":"Claude Code skill for publishing skills to GitHub and awesome-claude-skills lists. Encodes hard-won lessons from real publishing attempts.","archived":false,"fork":false,"pushed_at":"2026-03-30T12:10:45.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T14:20:11.188Z","etag":null,"topics":["ai","automation","claude-code","claude-code-skill","github","publishing","skill-publishing"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wan-huiyan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T13:18:55.000Z","updated_at":"2026-03-30T12:10:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wan-huiyan/publish-skill","commit_stats":null,"previous_names":["wan-huiyan/publish-skill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wan-huiyan/publish-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wan-huiyan%2Fpublish-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wan-huiyan%2Fpublish-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wan-huiyan%2Fpublish-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wan-huiyan%2Fpublish-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wan-huiyan","download_url":"https://codeload.github.com/wan-huiyan/publish-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wan-huiyan%2Fpublish-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31410418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","claude-code","claude-code-skill","github","publishing","skill-publishing"],"created_at":"2026-04-04T19:24:22.297Z","updated_at":"2026-04-04T19:24:22.985Z","avatar_url":"https://github.com/wan-huiyan.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Publish Skill - Claude Code Skill\n[![GitHub release](https://img.shields.io/github/v/release/wan-huiyan/publish-skill)](https://github.com/wan-huiyan/publish-skill/releases) [![Claude Code](https://img.shields.io/badge/Claude_Code-skill-orange)](https://claude.com/claude-code) [![license](https://img.shields.io/github/license/wan-huiyan/publish-skill)](LICENSE) [![last commit](https://img.shields.io/github/last-commit/wan-huiyan/publish-skill)](https://github.com/wan-huiyan/publish-skill/commits)\n\nPublishing a Claude Code skill involves a dozen error-prone steps — repo structure, README, screenshots, marketplace submission, and client data scanning. This skill handles the full workflow so you only have to do each mistake once.\n\n## How It Works\n\n```\nStep 0: Client Data Audit     → Scan for company names, amounts, field names in\n                                SKILL.md, README, screenshots, git history\n\nStep 1: Repo Structure         → .claude-plugin packaging, skills/ directory, LICENSE\n                                (MIT — with independent rationale, not self-referential)\n\nStep 2: Write README           → 16-section template: screenshots, installation, limitations,\n                                version history. Pitfalls in strategic-then-implementation order\n\nStep 3: Hook Bundling          → If the skill benefits from auto-triggering, include\n                                hooks/ directory with ready-to-use scripts + settings.json snippet\n\nStep 4: Demo Screenshots       → Puppeteer-generated. For rich output, capture 2–4 focused\n                                sections (not one massive hero image)\n\nStep 5: Verify Claims          → Parallel research agents check thresholds and citations\n\nStep 6: Review Panel           → Multi-agent adversarial review of the README\n\nStep 7: GitHub Setup           → Create repo, set topics (or suggest in PR if contributing\n                                via fork — API requires owner access)\n\nStep 8: Awesome Lists          → (Optional) Submit PRs with correct formatting per list\n```\n\n## When to Use\n\n- A skill is ready to share publicly\n- You say \"publish this skill\", \"put this on GitHub\", or \"share this skill\"\n- You want to submit a skill to awesome-claude-skills marketplaces\n- You need to update an already-published skill's GitHub presence\n- \"Submit to awesome-claude-skills\" / \"add my skill to the awesome list\"\n- \"How do I let others install my skill?\" / \"I finished my skill, now what?\"\n- \"Push my skill to a public repo\" / \"generate a README and publish\"\n- \"Bump the version and republish\" / \"turn my local skill into a polished repo\"\n\n## Hard-Won Lessons Encoded\n\nThese rules were learned from real incidents during publishing:\n\n| Lesson | What Happened |\n|--------|--------------|\n| No \"Test plan\" in PR body | 3 of 4 awesome-list PRs had unnecessary test plan sections — inappropriate for doc-only PRs |\n| Never multi-PR from same fork | Two PRs to the same upstream from one fork — second push auto-closed the first |\n| Always add links in Origin | Bare paper references without URLs look incomplete — always add arxiv/DOI/GitHub links |\n| Interactive skills need process examples | Example Output showing a static taxonomy dump contradicts the claim that the skill is an \"interactive diagnostic\" |\n| Check list format before submitting | Each awesome-list has its own table/list format — match it exactly |\n| GitHub can't delete PRs | Only repo admins can delete PRs — be careful with what you open |\n| Fork contributors can't set topics | `gh repo edit --add-topic` requires admin access — suggest topics in PR description instead |\n| Multi-section screenshots beat single hero | For rich output skills, 2–4 focused section screenshots show variety better than one long image |\n| Don't cite your own skill as authority | \"MIT because publish-skill says so\" is circular — justify recommendations with independent reasoning |\n| Update SKILL.md FIRST, metadata second | Updated eval-suite, README, plugin.json, and marketplace.json to v1.5 — but forgot to add a version field to SKILL.md itself. The skill content is the primary artifact; metadata files follow it, not the other way around |\n\n## Example: What the Skill Produces\n\nWhen you say \"publish this skill\", the skill walks through each phase:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePhase 1: Pre-Flight\u003c/b\u003e — checks skill readiness\u003c/summary\u003e\n\n\u003e I've read the skill. A few things before we publish:\n\u003e\n\u003e - Version: 2.0.0 (update, not new)\n\u003e - The skill has an interactive 4-phase process — good, this isn't a static doc\n\u003e - No sensitive content detected\n\u003e - The GitHub repo `wan-huiyan/ai-trust-evaluation` already exists with v1.0\n\u003e\n\u003e Ready to update the repo with v2.0?\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePhase 3: README\u003c/b\u003e — writes a structured README with links\u003c/summary\u003e\n\n\u003e I've written the README with:\n\u003e - \"How It Works\" process flow diagram\n\u003e - \"Example Output\" showing the interactive diagnostic across 4 phases\n\u003e   (not a static taxonomy dump)\n\u003e - All 8 research papers linked to arxiv/Nature/USENIX\n\u003e - Installation instructions\n\u003e - Origin section with methodology and paper table\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePhase 5: Awesome Lists\u003c/b\u003e — optional, correct formatting\u003c/summary\u003e\n\n\u003e Submitted to ComposioHQ/awesome-claude-skills:\n\u003e - Forked repo, created branch `add-ai-trust-evaluation`\n\u003e - Added entry alphabetically in the correct table format\n\u003e - PR body has Summary section only (no test plan)\n\u003e - PR #425: https://github.com/ComposioHQ/awesome-claude-skills/pull/425\n\u003c/details\u003e\n\n## Installation\n\n### Claude Code\n\n**Option 1: Plugin install (recommended)**\n```bash\n/plugin marketplace add wan-huiyan/publish-skill\n/plugin install publish-skill@wan-huiyan-publish-skill\n```\n\n**Option 2: Git clone**\n```bash\ngit clone https://github.com/wan-huiyan/publish-skill.git ~/.claude/skills/publish-skill\n```\n\n### Cursor\n\nCursor supports skills via `~/.cursor/skills/` (Cursor 2.4+), though global discovery can be flaky. Options from most to least reliable:\n\n**Option 1: Per-project rule (most reliable)**\n```bash\nmkdir -p .cursor/rules\n# Create .cursor/rules/publish-skill.mdc with the content of SKILL.md\n# Add frontmatter: alwaysApply: true\n```\n\n**Option 2: npx skills CLI**\n```bash\nnpx skills add wan-huiyan/publish-skill --global\n```\n\n**Option 3: Manual global install**\n```bash\ngit clone https://github.com/wan-huiyan/publish-skill.git ~/.cursor/skills/publish-skill\n```\n\n## Eval Suite Coverage\n\nThe skill includes a comprehensive evaluation suite (`eval-suite.json`) with **45 trigger tests**, **12 functional test cases**, and **16 edge cases**.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTrigger tests (45)\u003c/b\u003e — validate when the skill should and shouldn't activate\u003c/summary\u003e\n\n- 25 positive triggers: \"publish this skill\", \"republish\", \"share my .claude skill\", compound intents, etc.\n- 20 negative triggers: \"deploy to production\", \"publish my npm package\", \"make a GitHub repo\" (no skill context), \"improve this skill's quality\", etc.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFunctional test cases (12)\u003c/b\u003e — cover every major workflow step\u003c/summary\u003e\n\n| Test case | What it validates |\n|---|---|\n| `basic_publish_flow` | Full publish pipeline: SKILL.md, README, LICENSE, plugin.json, marketplace.json, valid install commands |\n| `repo_structure_validation` | Correct directory structure with .claude-plugin, skills/, LICENSE |\n| `awesome_list_submission` | Fork workflow, alphabetical ordering, categories, description length, no test plan in PR |\n| `client_data_audit` | Sanitization, git history warning, orphan branch cleanup, visual asset scanning |\n| `update_existing_repo` | Version bump across all 7 locations (SKILL.md, nested copy, plugin.json, marketplace.json, README) |\n| `screenshot_generation` | Puppeteer usage, docs/ output, node_modules cleanup, generic demo scenarios |\n| `threshold_verification` | Grounded vs heuristic labeling, ranking-based thresholds |\n| `portability_check` | Flags vendor-specific references, suggests placeholder names |\n| `review_panel` | Multi-agent review invocation, screenshot and limitations checks |\n| `link_verification` | Broken link detection, fork vs upstream attribution |\n| `hook_bundling` | hooks/ directory, settings.json config, timeout guidance, merge-friendly advice |\n| `version_bump_completeness` | All update locations bumped, stale version string check |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eEdge cases (16)\u003c/b\u003e — error paths, permissions, and unusual inputs\u003c/summary\u003e\n\n| Edge case | Category |\n|---|---|\n| `no_skill_md_found` | missing_deps |\n| `skill_with_no_frontmatter` | malformed_input |\n| `huge_skill_md` | scale_extreme |\n| `repo_already_exists` | invalid_path |\n| `skill_with_sensitive_data` | dangerous_input |\n| `no_github_cli` | missing_deps |\n| `unicode_skill_name` | unicode |\n| `empty_skill_md` | minimal_input |\n| `fork_contributor_permissions` | permissions |\n| `multiple_skills_batch` | scale_extreme |\n| `network_failure_mid_publish` | missing_deps |\n| `yaml_frontmatter_conflict` | malformed_input |\n| `marketplace_name_collision` | conflict |\n| `skill_with_hooks_already` | existing_content |\n| `repo_not_owned_by_user` | permissions |\n| `puppeteer_not_available` | missing_deps |\n\u003c/details\u003e\n\n## Related Skills\n\n- [skill-creator](https://docs.anthropic.com/en/docs/claude-code/skills) — for creating skills from scratch\n- claudeception — for extracting skills from work sessions (built-in skill, no separate repo)\n- [agent-review-panel](https://github.com/wan-huiyan/agent-review-panel) — for stress-testing skills before publishing\n\n## Limitations\n\n- Requires an existing SKILL.md before use — does not create skills from scratch (use skill-creator for that)\n- Screenshot generation requires Puppeteer; skipped automatically if not installed\n- Does not submit to awesome-claude-skills automatically — the PR step requires manual review\n\n## Origin\n\nExtracted via Claudeception from a multi-session publishing workflow that included:\n- Publishing [ai-trust-evaluation](https://github.com/wan-huiyan/ai-trust-evaluation) through v1.0 → v2.0 → v3.0\n- Publishing [agent-review-panel](https://github.com/wan-huiyan/agent-review-panel) through v2.0 → v2.5\n- Submitting both to [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) and [travisvn/awesome-claude-code](https://github.com/travisvn/awesome-claude-code)\n- Debugging auto-closed PRs, fixing formatting, and learning the hard way about GitHub fork behavior\n\n## Version History\n\n| Version | Date | Changes |\n|---|---|---|\n| 1.6.0 | 2026-03-31 | Add \"update SKILL.md first\" lesson after metadata-only version bump missed the skill itself |\n| 1.5.0 | 2026-03-31 | Expand eval suite: 35→45 triggers, 6→12 test cases, 8→16 edge cases; strengthen assertions on existing tests |\n| 1.4.0 | 2026-03-24 | Enrich trigger description, add eval suite, add composability metadata |\n| 1.3.0 | 2026-03-24 | Add hooks bundling, multi-section screenshots, fork guidance, Why MIT rationale, pitfalls restructuring |\n| 1.2.0 | 2026-03-23 | Add awesome-claude-skills submission guidelines, domain-distance guidance |\n| 1.1.0 | 2026-03-22 | Add Step 0 client data audit, PR editing workflow |\n| 1.0.0 | 2026-03-21 | Initial release |\n\n## Acknowledgements\n\nTrigger accuracy and eval suite improved using [schliff](https://github.com/Zandereins/schliff) — an autonomous skill scoring and improvement framework.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwan-huiyan%2Fpublish-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwan-huiyan%2Fpublish-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwan-huiyan%2Fpublish-skill/lists"}