docs(distribution): round 4 heterogeneous: static release badge, announcement drafts for dev.to/Reddit/HN/LinkedIn, SkillX/aitmpl/LLMBase/MCPMarket probed

Author: francescobianco

DISTRIBUTION.md

@@ -19,12 +19,12 @@ The highest-value targets: users install directly from here.
 | Channel | URL | How to get listed | Status | Date | Notes |
 |---|---|---|---|---|---|
 | Skills.sh (Vercel) | https://www.skills.sh/ | Indexed from public GitHub repos with `skills/*/SKILL.md`; installs counted via `npx skills add openapi/openapi-skills`. Verify the repo appears in search | submitted | 2026-06-10 | Install command verified working (11 skills detected, installs to 19+ agents); first install registered. Re-check search indexing in a few days |
-| SkillX | https://github.com/nextlevelbuilder/skillx | Marketplace with semantic search/ratings; submit per their CLI/registry flow | todo | | |
+| SkillX | https://github.com/nextlevelbuilder/skillx | Unclear: the `skillx` npm CLI is a local skill-script runner, not a registry publisher; no submit path found in the repo | todo | 2026-06-10 | Low priority — revisit if the marketplace materializes |
 | Skills Directory | https://www.skillsdirectory.com/ | **Manual web form** at https://www.skillsdirectory.com/submit (reviewed before publishing) | todo | | Security-vetted listing is good trust signal for a B2B brand. Form is client-side — needs a human, ~2 min |
-| MCP Market — Skills section | https://mcpmarket.com/tools/skills | Submit skill/tool via their form | todo | | Same site can also list the Openapi MCP server |
+| MCP Market — Skills section | https://mcpmarket.com/tools/skills | Submit skill/tool via their form | todo | 2026-06-10 | Rate-limits automated access (429) — manual submission needed |
 | Claude Skills Hub | https://claudeskills.info/ | Submission/indexing of SKILL.md repos | todo | | 658+ skills indexed; site blocks automated fetch (403) — check submission path manually |
 | AwesomeSkills.dev | https://www.awesomeskills.dev/en | **Manual web form** at https://www.awesomeskills.dev/en/submit — paste the GitHub URL, auto-detects everything, live instantly (no moderation) | todo | | Client-side React form, no public API — needs a human, ~30 s |
-| LLMBase skills directory | https://llmbase.ai/skills/ | Submission form | todo | | |
+| LLMBase skills directory | https://llmbase.ai/skills/ | Submission form | todo | 2026-06-10 | Blocks automated access (403) — manual check needed |
 
 ## 2. Official Anthropic channels
 
@@ -91,12 +91,15 @@ Not this repo, but the same audience: each MCP listing should cross-link the ski
 
 ## 8. Community announcements (one-shot)
 
+Ready-to-publish drafts live in [`distribution/announcements/`](distribution/announcements/) — they must be posted by a human from a personal/company account (stealth or automated posting would backfire on these platforms).
+
 | Channel | URL | Status | Date | Notes |
 |---|---|---|---|---|
-| Reddit r/ClaudeAI | https://www.reddit.com/r/ClaudeAI/ | todo | | |
-| Reddit r/ClaudeCode | https://www.reddit.com/r/ClaudeCode/ | todo | | |
-| Hacker News (Show HN) | https://news.ycombinator.com/ | todo | | Best paired with the blog post |
-| dev.to / Hashnode | https://dev.to/ | todo | | Tutorial-style article |
+| Reddit r/ClaudeAI | https://www.reddit.com/r/ClaudeAI/ | todo | 2026-06-10 | Draft ready: [reddit-claudeai.md](distribution/announcements/reddit-claudeai.md) — affiliation disclosed, A/B data as the hook |
+| Reddit r/ClaudeCode | https://www.reddit.com/r/ClaudeCode/ | todo | 2026-06-10 | Same draft, adapt the title; don't post to both the same day |
+| Hacker News (Show HN) | https://news.ycombinator.com/ | todo | 2026-06-10 | Draft ready: [show-hn.md](distribution/announcements/show-hn.md) — submit + first comment; pair with the dev.to/blog post live |
+| dev.to / Hashnode | https://dev.to/ | todo | 2026-06-10 | Draft ready: [dev-to-article.md](distribution/announcements/dev-to-article.md) — also reusable for the Openapi blog |
+| LinkedIn (company + personal) | https://www.linkedin.com/company/openapi-com | todo | 2026-06-10 | Draft ready (IT + EN): [linkedin.md](distribution/announcements/linkedin.md) |
 | Product Hunt | https://www.producthunt.com/ | todo | | Optional, needs preparation |
 
 ---
@@ -124,3 +127,4 @@ Not this repo, but the same audience: each MCP listing should cross-link the ski
 | 2026-06-10 | Round 3 checks: PR #276 still open (only Vercel deploy bot comment); skills.sh still not indexing the repo (page 404) — added the official skills.sh badge to the README, which may trigger their crawler |
 | 2026-06-10 | Clarified Anthropic marketplace path: official is invite-only/curated (no application); submissions go to the **community marketplace** via in-app form (claude.ai/settings/plugins/submit, login required — human step). `claude plugin validate` passes, ready to submit |
 | 2026-06-10 | README badges: license badge switched to static shields.io image (no GitHub-API computation), skills.sh badge added |
+| 2026-06-10 | Round 4 (heterogeneous): release badge made static too (bump manually on new releases); SkillX investigated (npm CLI is a script runner, no registry submit — deprioritized); aitmpl contribution path identified (in-repo component PR with attribution, heavier — future option); LLMBase 403 / MCP Market 429 to automation — manual forms; 4 announcement drafts written in `distribution/announcements/` (dev.to, Reddit, Show HN, LinkedIn IT+EN) ready for human posting |

README.md

@@ -7,7 +7,7 @@
   <h4>Agent skills to interact with <a href="https://openapi.com/">Openapi®</a> APIs from Claude Code and any SKILL.md-compatible agent</h4>
 
 [![Skills CI](https://github.com/openapi/openapi-skills/actions/workflows/skills.yml/badge.svg)](https://github.com/openapi/openapi-skills/actions/workflows/skills.yml)
-[![Release](https://img.shields.io/github/v/release/openapi/openapi-skills)](https://github.com/openapi/openapi-skills/releases)
+[![Release](https://img.shields.io/badge/release-v0.1.0-blue)](https://github.com/openapi/openapi-skills/releases)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-11-blueviolet)](skills/)
 [![skills.sh](https://skills.sh/b/openapi/openapi-skills)](https://skills.sh/openapi/openapi-skills)

distribution/announcements/dev-to-article.md

@@ -0,0 +1,38 @@
+<!-- Draft for dev.to (publish from Francesco's/Openapi's account).
+     Suggested tags: ai, claudecode, api, agentskills -->
+
+# We measured what agent skills actually do: same task, half the time, half the cost
+
+At [Openapi](https://openapi.com) we publish 400+ APIs (company data, KYC, e-invoicing, e-signatures…). Like everyone this year, we watched coding agents start consuming APIs directly. So we packaged our platform knowledge as **agent skills** — plain `SKILL.md` files — and, before announcing anything, we asked the obvious question: *do skills actually help, or does a good model figure it out anyway?*
+
+## The experiment
+
+Same prompt, two headless Claude Code agents:
+
+> "All we know about a supplier is its VAT number: 12485671007. Find the company name, whether it's active, the registered office, and the province/region of its ZIP code. Credentials are in the environment. Be frugal: paid requests cost wallet credit."
+
+- Agent **A** ran in an empty workspace.
+- Agent **B** had our skills installed in `.claude/skills/`.
+
+Both solved it. The difference was *how*:
+
+| | time | turns | cost | paid API calls |
+|---|---|---|---|---|
+| without skills | 108.5s | 13 | $0.75 | 2 |
+| **with skills** | **45.3s** | **9** | **$0.38** | **1** |
+
+The bare agent had to discover our auth model (Basic auth mints scoped Bearer tokens) by trial and error. The skilled agent read the auth skill, minted a 1-hour token scoped to exactly two endpoints — and then did something we didn't script: it noticed in the company skill that the cheap `IT-start` endpoint already includes province and region, so it **skipped the second API call entirely**. The skill didn't just guide it; it let the agent be smarter about cost than our own demo script was.
+
+The harness is in the repo (`test/run_comparison.sh`) — you can reproduce the comparison with your own account.
+
+## What's inside
+
+11 skills, one per domain: auth/tokens, company data (IT/EU/worldwide), official business documents, risk/KYC, data verification, geo/cadastre, SMS/PEC/postal mail, eIDAS e-signatures, e-invoicing via SDI, automotive, utilities. Each `SKILL.md` is self-contained: endpoints, async patterns, billing caveats, compliance warnings.
+
+```bash
+npx skills add openapi/openapi-skills
+```
+
+Works with Claude Code, Codex, Cursor, Gemini CLI and any SKILL.md-compatible agent. Also installable as a Claude Code plugin: `/plugin marketplace add openapi/openapi-skills`.
+
+Repo: https://github.com/openapi/openapi-skills — feedback and issues welcome.

distribution/announcements/linkedin.md

@@ -0,0 +1,30 @@
+<!-- Draft for LinkedIn (Openapi company page + personal repost).
+     Italian first (home market), English version below. -->
+
+## Versione italiana
+
+Gli agenti AI hanno iniziato a consumare API. Noi gli abbiamo dato il manuale d'uso. 🧩
+
+Abbiamo pubblicato le **Openapi Skills**: 11 skill open source (standard SKILL.md) che insegnano a Claude Code, Codex, Cursor e a qualsiasi coding agent come usare le nostre API — autenticazione, dati aziendali, visure, KYC, fatturazione elettronica, firme digitali e altro.
+
+Prima di annunciarle le abbiamo misurate: stesso compito, un agente senza skill e uno con le skill installate. Risultato: **metà del tempo, metà del costo, e una chiamata API a pagamento in meno** — l'agente ha letto nella skill che l'endpoint più economico bastava, e ha evitato da solo la seconda chiamata.
+
+Tutto open source, test harness incluso:
+👉 github.com/openapi/openapi-skills
+Installazione: `npx skills add openapi/openapi-skills`
+
+#AI #API #ClaudeCode #AgentSkills #OpenSource
+
+## English version
+
+AI agents started consuming APIs. We gave them the manual. 🧩
+
+We've published **Openapi Skills**: 11 open-source skills (SKILL.md standard) that teach Claude Code, Codex, Cursor and any coding agent how to use our APIs — authentication, company data, official documents, KYC, e-invoicing, e-signatures and more.
+
+Before announcing, we measured them: same task, one agent without the skills and one with them installed. Result: **half the time, half the cost, one fewer paid API call** — the agent read in the skill that the cheapest endpoint was enough and skipped the second call on its own.
+
+All open source, A/B test harness included:
+👉 github.com/openapi/openapi-skills
+Install: `npx skills add openapi/openapi-skills`
+
+#AI #API #ClaudeCode #AgentSkills #OpenSource

distribution/announcements/reddit-claudeai.md

@@ -0,0 +1,18 @@
+<!-- Draft for r/ClaudeAI or r/ClaudeCode (post from Francesco's personal account;
+     flair: Productivity / Showcase. Disclose affiliation — Reddit hates stealth marketing. -->
+
+**Title:** We A/B tested our agent skills: same prompt with and without them — half the time, half the cost, and the skilled agent made one less paid API call
+
+**Body:**
+
+I work at Openapi (Italian API marketplace) and we just published our services as agent skills. Before announcing, we wanted proof they actually matter, so we built a small harness: the same prompt ("here's a VAT number, find who the company is and where it's based, credentials in env, be frugal") run by two headless Claude Code agents — one bare, one with the skills installed.
+
+Results: bare = 108s / 13 turns / $0.75 / 2 paid calls. Skilled = 45s / 9 turns / $0.38 / 1 paid call.
+
+The part that surprised us: the skilled agent read in the skill that the cheapest endpoint already includes the geographic data, and skipped the second API call on its own. Our own demo script wasn't that frugal.
+
+The comparison harness is in the repo (`test/run_comparison.sh`) if you want to run the same experiment on your own skills — I'd honestly love to see numbers from other domains.
+
+Repo: https://github.com/openapi/openapi-skills (install: `npx skills add openapi/openapi-skills`)
+
+Disclosure: I'm on the Openapi team. The skills require an Openapi account; the test harness and the skill-writing patterns are MIT and useful regardless.

distribution/announcements/show-hn.md

@@ -0,0 +1,18 @@
+<!-- Draft for Hacker News Show HN (submit from Francesco's account).
+     Best paired with the dev.to/blog post already live. Keep the first comment ready. -->
+
+**Title:** Show HN: We A/B tested agent skills – same prompt, with and without them
+
+**URL:** https://github.com/openapi/openapi-skills
+
+**First comment (post immediately after submitting):**
+
+Hi HN, I work at Openapi, an Italian API marketplace (company registries, KYC, e-invoicing, e-signatures).
+
+We packaged our platform knowledge as agent skills (the SKILL.md format that Claude Code, Codex and Cursor all read now). The interesting part isn't the skills themselves — it's the test harness we built to justify them. It runs the same prompt through two headless agents, one bare and one with skills installed, and diffs the outcome: 108s/13 turns/$0.75/2 paid API calls without skills vs 45s/9 turns/$0.38/1 paid call with them.
+
+The skilled agent actually outperformed our own demo script: the skill mentions that the cheapest endpoint already returns province/region, so the agent skipped a second paid call we had assumed was needed.
+
+Everything is MIT: the 11 skills, the knowledge base they're generated from (vendored OpenAPI specs + a distillation pipeline), and the A/B harness (test/run_comparison.sh) — the harness works for any skills repo, not just ours.
+
+Happy to answer questions about the format, what we got wrong on the first iteration (skills that linked to internal docs instead of being self-contained), or the economics of agents consuming metered APIs.