skill-publish · Open Source Project Publishing to GitHub One-Stop Pipeline
A set of standard operating procedures to transform a "finished local Skill / open-source project" into something on GitHub that is searchable, understandable, desirable to click on, and appealing to download and try. The complete flow consists of 6 Phases, executed in order.
When to Use (Trigger Conditions)
- ✅ You have just finished a local Skill (e.g., knowledge management tool, image generation script, Agent workflow) and are ready to make it public on GitHub
- ✅ You want to give an existing repository a "star-growth checkup" by repackaging the About / Topics / README
- ✅ You want to publish a versioned Release with well-written Release Notes
- ✅ You want to simultaneously generate promotional posts for platforms like Juejin / V2EX / Xiaohongshu / Jike
- ❌ Not for writing code / fixing bugs / doing Code Review (use other skills for those)
Phase 1 — Legal Compliance Check (Do this first; fixing it later is much more costly)
1.1 Trademark & Brand Term Scan
Scan README.md / SKILL.md / script files for the following risky terms:
- Registered trademarks prohibited as product names:
ChatGPT,GPT-4,Douyin,WeChat,App Store,YouTube,Google,Facebook, etc.- ✅ Correct approach: Use descriptive phrases like "Compatible with OpenAI series models" or "Can call the xx platform API"; do not use brand names as product name fields
- Trademark symbols: Unless you actually hold a registration certificate, do not add ® / ™ after your own project name
- GitHub-related logos: GitHub Logo, Octocat image are prohibited from being directly placed in the repository as decoration (unless you have GitHub authorization); "GitHub" as a platform name can be normally mentioned
- API Vendor Names: Writing "Seedream / DALL·E 3 / FLUX and other image generation services" is normal descriptive usage; do not directly copy their Logos into README as decorative images
- Fonts: If the README contains demonstration screenshots, the decorative fonts in the screenshots must be open-source, free, and commercially usable fonts (Source Han Sans / Noto Sans / ZCOOL Happy Font, etc.); do not use unauthorized FounderType / Hanyi / Monotype fonts
- Portraits: Real person avatars/photos used in example images must be taken by yourself or from Unsplash / Pexels under CC0 license; do not directly grab others' photos from social platforms
- Sensitive words: Politics/pornography/drugs/violence/gambling/minors → zero tolerance, delete immediately
1.2 License Format & Selection Compliance
Open-source projects must have a LICENSE file; without one, it defaults to "All Rights Reserved," making others hesitant to use it.
- Default Recommendation: MIT License (most permissive, star-growth friendly, enterprises and individuals can use it)
- The first line of the LICENSE file must strictly be
MIT License; an empty first line or writing "MIT协议" in Chinese will cause GitHub not to recognize the License badge - Standard MIT template (copy and replace
[year]and[your username]):MIT License Copyright (c) [year] [your GitHub username] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - Validation:
gh repo view <owner>/<repo> --json licenseInfooutput must showMIT; otherwise, fix the LICENSE and push again
1.3 Sensitive Information & Privacy Cleanup
Globally grep for the following patterns; delete or replace with placeholders upon finding:
- Hardcoded secrets:
ghp_,sk-,xoxb-,AKIA,Bearerlong tokens - Personal privacy: phone numbers, real names (unless necessary), email, ID card numbers, bank card numbers, specific addresses
- Internal links: intranet
192.168.*/10.*, URLs withinternalkeywords, non-public private repository addresses - Temporary file paths: user local directory
C:\Users\xxx\type absolute paths → change to generic example$HOME/project
Phase 2 — GitHub Repository Packaging (About Bar Trio)
2.1 Description Formula (Directly Apply)
One-sentence core selling point in English + period + supplementary explanation in Chinese. Length 80–160 characters.
- The first 40 characters are most important (the GitHub mobile app search results page only truncates display to this many)
- The beginning must contain a search keyword; don't write empty phrases like "A useful little tool"
- Example:
- ❌ Bad: "Xiaohongshu image tool, very useful, come use it"
- ✅ Good: "Structured prompts + multi-model adapter for Xiaohongshu AI carousels. 8 style presets, 4 vendor fallback, stability first. 结构化 Prompt + 多模型适配器生成小红书图文素材，出图稳定优先"
2.2 Website Field (Don't Leave Empty!)
Priority:
- Project's actual Demo URL / Online work address / Author's Xiaohongshu homepage
- Author's own GitHub Profile:
https://github.com/<username> - Fallback: Fill in the repository's own URL (leaving empty = one less line of information in the About bar + one less click entry point)
2.3 Topics Combination Formula (8–12)
4 categories combined, all indispensable: Major Category (3–4) + Business Scenario (3–5) + Popular High-Frequency (2–3) + Niche (1–2)
- Character Rules: GitHub only accepts lowercase letters / numbers / single hyphen
-; no Chinese, no uppercase, no spaces, no starting or ending with underscore or- - Category Definitions and Examples:
Category Purpose Example Major Category Tech Stack Let users searching "python" and similar broad terms hit python,javascript,typescript,rust,go,cliBusiness Scenario Let users searching "What can I use for my second brain" hit second-brain,knowledge-management,xiaohongshu,llm-agent,note-takingPopular High-Frequency Tags most used by people on GitHub search, bring traffic prompt-engineering,stable-diffusion,agent-skill,workflow-automation,ai-coding-assistantNiche Precise audiences, less competition, higher conversion para-method,zettelkasten,harness,scaffolding,pkm,seedream
Complete example in templates/topics-formula.md.
Phase 3 — README Visual Enhancement (5 Standard Modules)
Goal: User scrolling to the first screen can understand "What is this? Can I use it? How do I run it?" within 3 seconds.
3.1 Hero First Screen (Mandatory)
# Project Name (<30 characters, bilingual optional)
<Project Hero Image / Decorative SVG — Width fills 900px>
> Slogan one-liner (<50 characters)
> Example: Build a structured second brain knowledge base in 3 minutes, 0 configuration 0 network, 100% pure Python standard library.
Core features 3–4 bullets:
- ✨ Feature 1: Write specific value, not "feature-rich"
- 🚀 Feature 2: Quantify numbers preferably (3 min / 0 dependency / 4-tier fallback / 8 presets)
- 🛡️ Feature 3: Engineering or stability selling point (automatic degradation / progress memory / idempotent safety)
3.2 Badge Trio (Mandatory)
Uniformly use shields.io style, placed on the line below the project name:
- Optional:
3.3 Screenshot/Demo Area (Mandatory)
- At least 1 image, placed at the very top of the Features section; preferably a GIF showing the core flow
- ALT text must be clear:
![Knowledge base 4-layer flowchart—Four-stage flow from Capture to Express] - If no image yet: Use a clear placeholder comment
<!-- TODO: Insert XX demo screenshot (suggestion: width 1600x900 png) -->, do not actually leave it empty
3.4 Installation & Running (Mandatory)
3-line method, copy-paste to run:
# 1. Clone
git clone https://github.com/<owner>/<repo>.git
cd <repo>
# 2. Run (add pip install if dependencies exist)
python run.py
# 3. Output looks like this (paste 5–10 lines of real stdout example)
[Phase 1/4] Capture ... OK → 3 files imported
[Phase 2/4] Index ... OK → 18 notes indexed
...
[DONE] Knowledge base built, time elapsed 2 min 34 s
3.5 Comparison Table / Why Reinvent the Wheel (Highly Recommended)
Answer the first visitor's soul-searching question "Why don't I use the existing XX instead of yours":
| Dimension | This Project | Handwritten Notes / Traditional Scaffolding | Commercial SaaS |
|---|---|---|---|
| Setup Cost | 0 | Days | Hours |
| Data Privacy | 100% Local Files | Local | Uploaded to Cloud |
| Customizability | Fully Open Source, Modifiable | Hard to Modify | Black Box |
| Price | Free | Free | Monthly/Yearly Subscription |
Phase 4 — Semantic Version Release
4.1 Version Number Rules (SemVer)
- First Release: Fixed at
v1.0.0(0.x.x gives the feeling "still in alpha, unstable") - Subsequent:
PATCH v1.0.1: Bug fixes, backward compatibleMINOR v1.1.0: Feature additions, backward compatibleMAJOR v2.0.0: Breaking changes, upgrade will cause errors
4.2 Release Notes Three-Part Template
See templates/release-notes-template.md for details.
- Title:
vX.Y.Z: One-sentence core selling point of the version (<30 characters) - Body: Core feature bullets → Quick start 3 lines → Welcome issue invitation
- Official Version: Do not check Draft / Do not check Pre-release / Check Set as latest release
4.3 Release Command
# After writing notes.md
gh release create v1.0.0 --target main \
--title "v1.0.0: First public release, core features launched" \
--notes-file release-notes.md \
--latest
Phase 5 — Multi-Platform Promotional Material Generation
5.1 Directory Structure (Standard)
tiezi/
└── <project name>/
├── juejin.md # Juejin: Most complete + strongest technical depth
├── v2ex.md # V2EX: Condensed version + programmer community tone
├── jike.md # Jike: Short, fast, quick + personal sharing tone
└── xiaohongshu.md # Xiaohongshu: Only submit if it's life/creation/efficiency content
5.2 Strategy for Choosing 3 Platforms
- Tech / AI Coding / Agent type projects: Juejin + V2EX + Jike
- AI Image Generation / Content Creation / Knowledge Management type: Xiaohongshu + Juejin + V2EX
- CLI / Pure Programmer Tools: Juejin + V2EX + Zhihu (Optional)
5.3 Share Post Structure Cardinal Rule (Rewrite if violated)
a → b → c → d four sections, order cannot be changed:
a. Opening: Development background / Real-world pain points (4–6 specific, real, relatable pain points for the reader, no empty talk)
b. Core feature introduction + 2–3 screenshot placeholders (Each placeholder clearly states "What content should this image contain + Recommended dimensions", not just "insert screenshot")
c. Key technical pitfalls encountered during implementation (3–4, including: specific manifestation → root cause → solution → lessons learned)
d. Conclusion: Project is open source → Welcome to download and try → Welcome to submit issues for discussion and feedback → Include GitHub repository link
5.4 Cardinal Red Lines
- ❌ Absolutely prohibited: Direct begging like "please give a star", "help click a star", "star it", "casually click star" (any variation is not allowed, including emoji hints like 🥺👉👈)
- ❌ Prohibited: Advertising tone (self-praise terms like "best on the market", "kills competitors", "first worldwide release")
- ✅ Correct tone: Personal developer sharing real pitfalls encountered; shortcomings can be honestly stated as "Currently XX is not yet supported, will be added in the next Release"
Detailed Markdown template in templates/share-post-template.md.
Phase 6 — Skill Project Self-Packaging & Publishing to GitHub
6.1 Skill Format Must Be Compliant
- Standard directory:
.trae/skills/<skill-name>/ - Required:
SKILL.md(frontmatter containingname+description, description must state both "what it does" and "when to call it") - Optional subdirectories:
scripts/Python/Bash helper scriptstemplates/Markdown / JSON / SVG templatesassets/Images, icons, example outputs
6.2 SKILL.md Content Cleanup (Last Sensitive Info Check)
- ❌ Must not contain: User local temporary paths (
C:\Users\xxx\AppData\Local\Temp\...), real tokens, private repository URLs, project temporary progress - ✅ Must be all: Reusable process descriptions, trigger conditions, safe examples, placeholders
6.3 Public Repository Required Files
Before pushing to GitHub, ensure the root directory has:
LICENSE(MIT, per Phase 1.2)README.md(Chinese, per Phase 3's 5 modules).gitignore(Python projects must add__pycache__/ *.pyc .DS_Storeetc.)
6.4 Post-Push "Bootstrap" Execution
After pushing the Skill project itself to GitHub, immediately re-run Phase 2 → Phase 4 of this process:
- Modify Description / Website / Topics
- Check License badge display
- Release v1.0.0
→ Once completed, this Skill itself is a qualified "skill-publish process demonstration project".
Execution Checklist (Follow for Invoking Phase)
| Step | Action | Output | Done |
|---|---|---|---|
| 1 | Phase 1 Legal Compliance Check: Trademarks / LICENSE format / Sensitive words / Privacy | A clean repository | ☐ |
| 2 | Phase 2 About Trio: Description written per formula + Website filled + Topics 8-12 combined per formula | About bar updated | ☐ |
| 3 | Phase 3 README Visual Enhancement: Hero + Badge + Screenshot + Install 3 lines + Comparison Table | README.md finalized | ☐ |
| 4 | Phase 4 Release: Semantic version v1.0.0 + Release Notes three-part release | GitHub Release page | ☐ |
| 5 | Phase 5 Promotional Material: Generate 3 pieces in tiezi//.md, strict a-b-c-d structure | 3 Markdown posts | ☐ |
| 6 | If it's a Skill → Phase 6 Package and publish + bootstrap steps 2-4 | Public repo live | ☐ |