6.8 KiB
publisher
Make your skills easy to understand and impossible to ignore.
The problem: Your skills get lost in the noise because people don't understand what they do or why they matter.
This tool: Generates clear, compelling descriptions that make people want to download your skills, then publishes everywhere with one command.
📋 Requirements
- bash
jq(brew install jq)ghCLI (brew install gh)skillsCLI (npm install -g skills)- git
⚡ What It Does
Your skills become easy to understand and impossible to ignore.
The tool:
- Generates compelling one-liners that explain your skill's value
- Creates clear, scannable descriptions following proven patterns
- Makes installation and setup obvious
- Publishes to GitHub and Skills automatically
One command turns technical skills into must-have tools.
🚀 Installation
skills install publisher
First-Time Setup
Requirements:
# Install dependencies
brew install jq gh
npm install -g skills
# Authenticate GitHub CLI
gh auth login
That's it! The tool handles the rest.
What Happens
The installation:
- Adds the
skill-publishercommand to your PATH - Validates all dependencies are installed
- Checks GitHub authentication
🔧 How It Works
Result: People understand your skill's value immediately and want to download it.
The process:
- Analyzes your SKILL.md to extract the core value proposition
- Generates 3 one-liner options using proven patterns:
- Pattern A: Continuous benefit ("Keep X fresh 24/7")
- Pattern B: Elimination ("Do X without Y")
- Pattern C: Automation ("Automatically X when Y")
- Creates clear descriptions that explain:
- What problem it solves (the WHY)
- What it does (the outcome)
- How to install (the steps)
- How it works (the process)
- Publishes to GitHub (creates repo if needed)
- Publishes to Skills with version from VERSION file
Smart workflow:
- Detects existing GitHub repos (won't duplicate)
- Asks for approval before overwriting README
- Auto-detects version from VERSION file
- Handles git initialization if needed
Example:
cd ~/bot/skills/my-skill
publisher
Output:
📝 Generating one-liner options...
A) Keep your thing updated automatically 24/7
B) Update things without manual intervention
C) Automatically sync data when changes occur
Choose one-liner (A/B/C/D): A
✅ Chosen: Keep your thing updated automatically 24/7
📄 Generating README.md...
📤 Publish to GitHub and Skills? (y/n): y
🐙 Creating GitHub repository...
✅ Published successfully!
📍 GitHub: https://github.com/user/my-skill
📍 Skills: https://skills.com/skills/my-skill
📚 Additional Information
Everything below is optional. The skill works out-of-the-box for most users.
This section contains:
- One-liner generation patterns
- README structure details
- File structure requirements
- Troubleshooting
You don't need to read this for initial use.
One-Liner Generation Patterns
The tool generates 3 options using proven patterns:
Pattern A: Continuous Benefit
Keep [thing] [desired state] [timeframe]
Examples:
- "Keep your Claude access token fresh 24/7"
- "Keep your backups synced automatically"
- "Keep dependencies up to date daily"
Pattern B: Elimination
[Do thing] without [pain point]
Examples:
- "Build cross-device tools without hardcoding paths"
- "Deploy skills without manual git commands"
- "Test code without manual setup"
Pattern C: Automation
Automatically [action] [thing] [when]
Examples:
- "Automatically refresh tokens before expiry"
- "Automatically backup workspace daily"
- "Automatically update skills on schedule"
Validation (good one-liners have):
- ✅ Specific (not generic)
- ✅ Benefit-focused (what it does FOR YOU)
- ✅ Outcome-oriented (the result you get)
- ✅ User-focused (not technical jargon)
README Structure Generated
Follows GitHub's documentation best practices:
Essential Sections
- Title + subtitle
- The problem: (explains pain point)
- This tool: (how it solves it)
- ⚡ What It Does (value proposition first)
- 🛠️ Getting Ready (OS + Homebrew installs + external tools)
- 🚀 Installation (the skill itself + verification)
- 🔧 How It Works (result → process)
Optional Sections (collapsible)
- Configuration options
- Troubleshooting
- For Developers
- For Developers
Key features:
- Inverted pyramid (conclusion first)
- Bold outcomes for scannability
- One idea per bullet
- Under 15% text highlighting
- Emojis for visual hierarchy
File Structure Required
Your skill directory should have:
your-skill/
├── SKILL.md # Required: with frontmatter
├── VERSION # Required: semantic version
├── scripts/ # Optional: your code
│ └── main.sh
├── README.md # Generated by this tool
└── .gitignore # Optional
SKILL.md frontmatter:
---
name: your-skill
description: Brief description here
---
VERSION file:
1.0.0
Troubleshooting
"gh: command not found"
Install and authenticate GitHub CLI:
brew install gh
gh auth login
"Permission denied (publickey)"
GitHub authentication failed.
Re-run:
gh auth refresh -s repo
"SKILL.md not found"
Create a SKILL.md with frontmatter:
---
name: my-skill
description: What it does
---
# my-skill
Longer description here.
"VERSION file not found"
Create a VERSION file:
echo "1.0.0" > VERSION
"Repository already exists"
If the repo exists on GitHub but not locally:
gh repo clone username/skill-name
cd skill-name
skill-publisher
For Developers
Architecture
Phase 1: Analysis
- Parses SKILL.md frontmatter (YAML)
- Extracts name, description
- Reads VERSION file
Phase 2: One-Liner Generation
- Applies 3 pattern formulas
- Lets user choose or write custom
- Updates SKILL.md frontmatter
Phase 3: README Generation
- Uses template structure
- Fills in skill-specific content
- Validates formatting (emojis, bold, structure)
Phase 4: Publishing
- Checks for existing GitHub repo
- Creates repo if needed (via
gh) - Pushes code
- Publishes to Skills (via
skills)
Future Enhancements (v1.1.0+)
- Full README generation from SKILL.md
- LLM-powered one-liner generation
- Automatic changelog generation
- Multiple platform support (npm, etc.)
License
MIT