1---
2name: skillmarketplace
3version: 4.0.0
4description: "Search, install, and publish skills. Use search_skills tool for discovery + auto-install. Manual publish via gateway."
5 
6metadata:
7  starchild:
8    emoji: "📦"
9    skillKey: skillmarketplace
10 
11user-invocable: true
12---
13 
14# Skill Market
15 
16## Searching & Installing Skills
17 
18**Always use the `search_skills` tool.** Do NOT manually curl, browse GitHub, or download SKILL.md files.
19 
20`search_skills` does everything automatically:
21 
221. **Local** — checks installed skills first
232. **Starchild community** — searches community-skills index
243. **skills.sh** — searches the global skills ecosystem (OpenClaw, Vercel, Anthropic, etc.)
254. **Auto-install** — installs the best match via `npx skills add` (default: `auto_install=true`)
26 
27### Usage
28 
29```
30search_skills(query="deploy")           # search + auto-install best match
31search_skills(query="trading")          # search + auto-install
32search_skills(query="k8s", auto_install=false)  # search only, don't install
33search_skills()                         # list all installed skills
34```
35 
36After `search_skills` installs a skill, it's immediately available. Call `skill_refresh()` only if you manually edited skill files.
37 
38### What NOT to do
39 
40- Do NOT `curl` GitHub repos to browse/download skills
41- Do NOT `mkdir -p skills/<name>` and manually write SKILL.md
42- Do NOT use `web_fetch` to download skill files
43- Do NOT use the old gateway search/install endpoints (they no longer exist)
44 
45---
46 
47## Publishing (Starchild Only)
48 
49Publishing still uses the gateway. Only Starchild-authored skills can be published.
50 
51### SKILL.md Requirements
52 
53```yaml
54---
55name: my-skill
56version: 1.0.0
57description: What this skill does
58author: your-name
59tags: [tag1, tag2]
60---
61```
62 
63| Field | Required | Rules |
64|-------|----------|-------|
65| `name` | Yes | Lowercase, alphanumeric + hyphens, 2-64 chars |
66| `version` | Yes | Semver (e.g. `1.0.0`) — immutable once published |
67| `description` | Recommended | Short summary for search |
68| `author` | Recommended | Author name |
69| `tags` | Recommended | Array of tags for discoverability |
70 
71### Publish Workflow
72 
73**Step 1: Validate the skill directory**
74 
75```bash
76SKILL_DIR="./skills/my-skill"
77head -20 "$SKILL_DIR/SKILL.md"
78```
79 
80**Step 2: Get OIDC token**
81 
82```bash
83TOKEN=$(curl -s --unix-socket /.fly/api \
84  -X POST -H "Content-Type: application/json" \
85  "http://localhost/v1/tokens/oidc" \
86  -d '{"aud": "skills-market-gateway"}')
87```
88 
89**Step 3: Build and send publish request**
90 
91```bash
92SKILL_DIR="./skills/my-skill"
93GATEWAY="https://skills-market-gateway.fly.dev"
94 
95PAYLOAD=$(python3 -c "
96import os, json
97files = {}
98for root, dirs, fnames in os.walk('$SKILL_DIR'):
99    for f in fnames:
100        full = os.path.join(root, f)
101        rel = os.path.relpath(full, '$SKILL_DIR')
102        with open(full) as fh:
103            files[rel] = fh.read()
104print(json.dumps({'files': files}))
105")
106 
107curl -s -X POST "$GATEWAY/skills/publish" \
108  -H "Authorization: Bearer $TOKEN" \
109  -H "Content-Type: application/json" \
110  -d "$PAYLOAD" | python3 -m json.tool
111```
112 
113### Response (201)
114 
115```json
116{
117  "namespace": "@554",
118  "name": "my-skill",
119  "version": "1.0.0",
120  "tag": "@554/[email protected]",
121  "download_url": "https://github.com/.../bundle.zip",
122  "release_url": "https://github.com/.../releases/tag/..."
123}
124```
125 
126### Version Rules
127 
128- Each version is **immutable** — once published, it cannot be overwritten.
129- To update, bump the version and publish again.
130 
131---
132 
133## Decision Tree
134 
135```
136User wants to find/install a skill
137  → Use search_skills(query) tool — it searches all sources and auto-installs
138  → NEVER curl GitHub or manually download files
139 
140User wants to list installed skills
141  → Use search_skills() with no query
142 
143User wants to publish a skill
144  → Validate SKILL.md frontmatter
145  → Get OIDC token (audience: skills-market-gateway)
146  → POST to /skills/publish
147 
148User wants to create a new skill
149  → Read the skill-creator skill first
150```
151