docs(openspec): define skill distribution delivery contract

README.md

@@ -13,6 +13,7 @@ at the skill's own directory in this repository:
 npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/company-research
 npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/url-to-markdown
 npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/brand-kit
+npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/app-store-api
 ```
 
 Install the whole canonical package — the `replynodes` umbrella plus every
@@ -22,12 +23,9 @@ focused skill — with the umbrella install:
 npx skills add replynodes/replynodes-agent-skills
 ```
 
-The repository-plus-`--skill` form, for example
-`npx skills add https://github.com/replynodes/replynodes-agent-skills --skill company-research`,
-is a compatibility limitation rather than the primary command: for a remote
-GitHub clone the current official `skills` CLI stops at the root `replynodes`
-skill and reports no matching focused skill. Use the focused directory command
-above instead.
+Canonical focused pages: [company-research](https://skills.sh/replynodes/replynodes-agent-skills/company-research), [url-to-markdown](https://skills.sh/replynodes/replynodes-agent-skills/url-to-markdown), and [app-store-api](https://skills.sh/replynodes/replynodes-agent-skills/app-store-api). The source repository is canonical; Skills.sh and ClawHub pages are separately read back and may lag or retain legacy slugs.
+
+Copyable GitHub Actions examples live in [`examples/github-actions/`](examples/github-actions/).
 
 | Skill | Use it for |
 | --- | --- |

SKILL.md

@@ -1,13 +1,22 @@
 ---
 name: replynodes
-description: "Use ReplyNodes when a user needs current public research: read a known URL as clean Markdown, get a domain's public brand kit or logo, search the web, or enrich a bounded company, competitor, app, or community brief."
+description: >-
+  Research the current public web with ReplyNodes, the keyless, read-only
+  public-data layer for AI agents. Use it to turn a known URL into clean
+  Markdown for LLM context, fetch a domain's public brand kit, colors, fonts,
+  or logo, run a web search, scrape or map a site, and build bounded, cited
+  briefs about a company, competitor, app, or community. Free and zero-auth
+  first for Markdown, Brand, Logo, and the reviewed /v1 web-search, scrape,
+  App Store, Google Play, Reddit, and YouTube reads; optional MCP enrichment
+  is keyed.
 license: MIT
 compatibility: "Network access is enough for the free, zero-auth Markdown and Brand hosts (Tier A, 20/day per capability) and the `img.replynodes.com` Logo host (no published fixed limit), and for the reviewed keyless `/v1` primitives (web search, single-page scrape, App Store, Google Play, Reddit, YouTube) admitted through the shared anonymous quota (Tier B, 10/day per capability); the keyless `GET https://api.replynodes.com/v1/brand/logo` route is Tier A (20/day). Authenticated continuation and deeper routes (site map/crawl, brand search/retrieve, Hacker News, MCP) need an API client or MCP-capable agent and REPLYNODES_API_KEY in a secret store; an existing authenticated free account has 500 credits."
 metadata:
   internal: false
   author: ReplyNodes
   version: "2.0.0"
   endpoint: https://mcp.replynodes.com/mcp
+  keywords: [web research, company research, competitor research, brand kit, url to markdown, web scraping, web search, app store research, reddit search, youtube research, public data, public web, keyless, zero-auth, read-only, ai agent]
 ---
 
 # ReplyNodes research skill

docs/distribution-growth-plan.md

@@ -0,0 +1,57 @@
+# Legitimate distribution growth plan
+
+Status: P0 implementation baseline. This document separates source work from external index state.
+
+## Canonical install funnel
+
+Use the canonical GitHub source and focused skill directories:
+
+```bash
+# Umbrella routing
+npx --yes skills add replynodes/replynodes-agent-skills
+
+# Priority focused skills
+npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/company-research
+npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/url-to-markdown
+npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/app-store-api
+```
+
+The focused directory commands are the primary public CTAs. The umbrella remains the canonical all-skills install; do not create duplicate top-level copies merely to hide registry/index differences.
+
+## 30-query discovery baseline
+
+Run the query set in `references/discovery-query-baseline.csv` against the public find/search surface available at the time. Record UTC time, exact query, target slug, visibility, rank only when the response exposes rank, competing result names, URL, and method. `not observable` is a valid rank value; it is not a negative result.
+
+Query families:
+
+- company research: company profile, business intelligence, prospect/account research, vendor due diligence, company domain research, first-party company brief;
+- URL conversion: URL to Markdown, webpage to Markdown, article extraction, docs page for LLM, HTML to Markdown, clean web context;
+- App Store: iOS app search, App Store reviews, app ratings, app privacy, developer apps, similar iPhone apps;
+- combined workflows: research SaaS competitors, public web research for agents, RAG page extraction, current public product research, no-key web research.
+
+## Daily baseline
+
+Record one immutable daily row in `references/distribution-daily-baseline.csv` after public readback:
+
+- external: Skills.sh visible installs, ClawHub downloads/installs/stars, GitHub stars, repository views/clones/referrers;
+- product: distinct downstream callers, requests, API-key creation after first attributed use, sibling-skill adoption, and two-UTC-day retention;
+- attribution: source URL/campaign, skill header/run ID where the existing contract supports it, and exclusions.
+
+External counters are display signals. They are never called genuine users, conversions, or retention. The 30-day window starts only after a verified post-merge readback and remains `PENDING` until the second eligible UTC day exists.
+
+## Upstream distribution actions
+
+1. Submit a focused correction PR/request to `vercel-labs/skills` for stale Skills.sh entries with canonical repo, branch, exact paths, source SHA, expected slugs, and install commands.
+2. Keep ClawHub links as acquisition surfaces only; reconcile `replynodes-ai` owner/slugs through the authenticated owner path. The current `brand-kit@1.0.0` reservation is blocked and must not be bypassed with a duplicate or invented version.
+3. Prefer useful integrations and community directories that accept canonical GitHub links and read-only capability descriptions. Measure referral traffic with existing UTM attribution; do not mass-submit or repeat submissions.
+4. Promote the five workflow examples through changelog/docs/community posts only when they solve a real developer task; never ask users to install repeatedly.
+
+## Acceptance evidence
+
+- exact source commit and changed-file list;
+- `git diff --check`, package validator, distribution tests;
+- clean focused and umbrella install logs with installed paths/content hashes;
+- one safe keyless smoke for each priority skill;
+- 30-query baseline with unavailable ranks called out;
+- public Skills.sh/ClawHub readback, including stale/soft-200 classification;
+- independent review of the exact PR head.

examples/github-actions/README.md

@@ -0,0 +1,14 @@
+# GitHub Actions examples
+
+These are copyable, bounded examples for real read-only research workflows. They are documentation examples, not an install loop: install a skill once in the agent environment, then reuse it. Each example links to the canonical source and uses public data only.
+
+- `company-research.yml` — produce a bounded company brief from a domain.
+- `url-to-markdown.yml` — convert a known public URL to Markdown.
+- `app-store-research.yml` — fetch one public App Store result.
+- `umbrella-research.yml` — install the umbrella router for mixed research tasks.
+- `scheduled-public-research.yml` — scheduled bounded public research with an explicit rate limit.
+
+Canonical source: https://github.com/replynodes/replynodes-agent-skills
+Skills.sh pages: https://skills.sh/replynodes/replynodes-agent-skills
+
+Each public request uses a bounded timeout and `--fail-with-body`; non-2xx responses, timeouts, and upstream rate limits fail the workflow rather than being retried indefinitely. The examples intentionally do not disable the CLI's normal telemetry behavior because they do not run the CLI install command at all: install once in the agent environment, then reuse it without manufacturing acquisition events.

examples/github-actions/app-store-research.yml

@@ -0,0 +1,29 @@
+name: ReplyNodes App Store research
+on:
+  workflow_dispatch:
+    inputs:
+      term:
+        description: Public iOS app search term
+        required: true
+        default: notion
+permissions:
+  contents: read
+jobs:
+  app-store:
+    runs-on: ubuntu-latest
+    steps:
+      # Install once in the agent environment:
+      # npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/app-store-api
+      # Source: https://github.com/replynodes/replynodes-agent-skills
+      # Focused page: https://www.skills.sh/replynodes/replynodes-agent-skills/app-store-api
+      - name: Search public App Store data
+        env:
+          SEARCH_TERM: ${{ inputs.term }}
+        run: |
+          set -euo pipefail
+          curl --fail-with-body --max-time 20 --get 'https://api.replynodes.com/v1/appstore/search' \
+            --data-urlencode "term=${SEARCH_TERM}" --data 'country=us' --data 'num=1' -o appstore.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: app-store-research
+          path: appstore.json

examples/github-actions/company-research.yml

@@ -0,0 +1,32 @@
+name: ReplyNodes company research
+on:
+  workflow_dispatch:
+    inputs:
+      domain:
+        description: Public company domain
+        required: true
+        default: stripe.com
+permissions:
+  contents: read
+jobs:
+  research:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Install once in the agent environment:
+      # npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/company-research
+      # Source: https://github.com/replynodes/replynodes-agent-skills
+      # Focused page: https://www.skills.sh/replynodes/replynodes-agent-skills/company-research
+      - name: Read public evidence
+        env:
+          DOMAIN: ${{ inputs.domain }}
+        run: |
+          set -euo pipefail
+          curl --fail-with-body --max-time 20 "https://md.replynodes.com/https://${DOMAIN}/" -o company.md
+          curl --fail-with-body --max-time 20 "https://brand.replynodes.com/${DOMAIN}.json" -o brand.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: company-research-evidence
+          path: |
+            company.md
+            brand.json

examples/github-actions/scheduled-public-research.yml

@@ -0,0 +1,24 @@
+name: Scheduled bounded public research
+on:
+  schedule:
+    - cron: '17 8 * * 1'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  snapshot:
+    runs-on: ubuntu-latest
+    steps:
+      # Install once in the agent environment, not on every scheduled run:
+      # npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/company-research
+      # Source: https://github.com/replynodes/replynodes-agent-skills
+      # Focused page: https://www.skills.sh/replynodes/replynodes-agent-skills/company-research
+      - name: Read one bounded public homepage
+        run: |
+          set -euo pipefail
+          curl --fail-with-body --max-time 20 'https://md.replynodes.com/https://replynodes.com/' -o replynodes-home.md
+          test -s replynodes-home.md
+      - uses: actions/upload-artifact@v4
+        with:
+          name: scheduled-public-research
+          path: replynodes-home.md

examples/github-actions/umbrella-research.yml

@@ -0,0 +1,18 @@
+name: ReplyNodes umbrella research setup
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      # Install once in the agent environment:
+      # npx --yes skills add replynodes/replynodes-agent-skills
+      # Source: https://github.com/replynodes/replynodes-agent-skills
+      # Skills.sh: https://www.skills.sh/replynodes/replynodes-agent-skills
+      - name: Show canonical source
+        run: |
+          printf '%s\n' 'ReplyNodes umbrella installed from:'
+          printf '%s\n' 'https://github.com/replynodes/replynodes-agent-skills'
+          printf '%s\n' 'Use it for bounded public web, brand, app, and competitor research.'

examples/github-actions/url-to-markdown.yml

@@ -0,0 +1,29 @@
+name: ReplyNodes URL to Markdown
+on:
+  workflow_dispatch:
+    inputs:
+      url:
+        description: Public HTTP(S) URL
+        required: true
+        default: https://replynodes.com/
+permissions:
+  contents: read
+jobs:
+  markdown:
+    runs-on: ubuntu-latest
+    steps:
+      # Install once in the agent environment:
+      # npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/url-to-markdown
+      # Source: https://github.com/replynodes/replynodes-agent-skills
+      # Focused page: https://www.skills.sh/replynodes/replynodes-agent-skills/url-to-markdown
+      - name: Fetch public Markdown
+        env:
+          URL: ${{ inputs.url }}
+        run: |
+          set -euo pipefail
+          case "$URL" in http://*|https://*) ;; *) echo 'HTTP(S) URL required' >&2; exit 2;; esac
+          curl --fail-with-body --max-time 20 "https://md.replynodes.com/${URL}" -o page.md
+      - uses: actions/upload-artifact@v4
+        with:
+          name: url-to-markdown-output
+          path: page.md

openspec/changes/skills-distribution-growth/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-09

openspec/changes/skills-distribution-growth/design.md

@@ -0,0 +1,48 @@
+# Design: Canonical source with separately verified registries
+
+## Architecture and boundaries
+
+The GitHub repository is the canonical source artifact. Skills.sh is an external index of GitHub content; a HTTP 200 or rendered page does not prove fresh indexing, correct slug mapping, installability, or source identity. ClawHub is a separate publisher artifact owned by `replynodes-ai`; its downloads, rolling install counters, versions, scanner state, and provenance must be read independently.
+
+No code path is added between these systems. This change is documentation, metadata, examples, evidence templates, and deterministic validation only.
+
+## Install funnel
+
+- Umbrella CTA: `npx --yes skills add replynodes/replynodes-agent-skills`.
+- Focused CTA: direct GitHub skill directory URL, for example:
+  `npx --yes skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/company-research`.
+- Focused repository-plus-`--skill` forms remain compatibility probes, not the primary CTA, because a repository with a root `SKILL.md` can stop discovery before nested skills.
+- `--full-depth` is a diagnostic/workaround flag, not evidence that a user-friendly install funnel is fixed.
+
+The clean-install matrix records command, CLI version, HOME/workdir isolation, source SHA, installed path, content hash, and exact failure. It uses `DISABLE_TELEMETRY=1` for internal probes only; user-facing commands never include that variable.
+
+## Metadata and taxonomy
+
+Priority descriptions use task language (`company research`, `URL to Markdown`, `App Store research`, `public web research`) with bounded truthful keywords. They preserve read-only and keyless-first limits already supported by live production evidence. Legacy slugs are documented as discrepancies and never reintroduced as public taxonomy entries.
+
+## Workflow examples
+
+Five GitHub Actions files cover company research, URL-to-Markdown, App Store research, umbrella routing, and a scheduled public-research workflow. Each example:
+
+- is manually dispatched or explicitly scheduled;
+- uses `npx skills add` only as a documented comment/CTA, not on every push;
+- performs bounded public reads only;
+- uses placeholders or GitHub secret references without printing them;
+- links to the canonical source and skill page;
+- states that upstream/rate-limit failure must be surfaced, not retried indefinitely.
+
+## Measurement
+
+`references/discovery-query-baseline.csv` stores exactly 30 task-language queries, target slugs, UTC observation fields, method, visibility, observable rank, competitors, and evidence URL. `references/distribution-daily-baseline.csv` separates:
+
+- external signals: Skills.sh installs, ClawHub downloads/installs/stars, GitHub stars and traffic;
+- product signals: downstream callers, requests, key creation after attributed use, sibling adoption, and two-UTC-day retention;
+- attribution: only existing bounded IDs/UTM/run headers where available.
+
+External counters are never labeled genuine users, conversions, or retained callers. The observation window starts only after post-merge public readback and remains `PENDING` until two eligible UTC calendar days exist.
+
+## Verification and rollback
+
+Required gates are strict OpenSpec validation, distribution tests, `git diff --check`, exact-head changed-file review, public URL/status readback, and safe keyless smoke evidence for documented routes. A clean-install failure is recorded as a blocker with its actual error. All implementation changes are additive/documentation-focused and revertible without runtime migration.
+
+External correction requests to Skills.sh or ClawHub are owner/operator actions after this PR; this repository change must not pretend those actions happened.