diff --git a/README.md b/README.md index 1dc10c8..b0c509e 100644 --- a/README.md +++ b/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 | | --- | --- | diff --git a/SKILL.md b/SKILL.md index b1f4656..9c66e20 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,14 @@ --- 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: @@ -8,6 +16,7 @@ metadata: 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 diff --git a/docs/distribution-growth-plan.md b/docs/distribution-growth-plan.md new file mode 100644 index 0000000..33bce86 --- /dev/null +++ b/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. diff --git a/examples/github-actions/README.md b/examples/github-actions/README.md new file mode 100644 index 0000000..4b8023d --- /dev/null +++ b/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. diff --git a/examples/github-actions/app-store-research.yml b/examples/github-actions/app-store-research.yml new file mode 100644 index 0000000..838a2ea --- /dev/null +++ b/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 diff --git a/examples/github-actions/company-research.yml b/examples/github-actions/company-research.yml new file mode 100644 index 0000000..78e27f3 --- /dev/null +++ b/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 diff --git a/examples/github-actions/scheduled-public-research.yml b/examples/github-actions/scheduled-public-research.yml new file mode 100644 index 0000000..fae34bb --- /dev/null +++ b/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 diff --git a/examples/github-actions/umbrella-research.yml b/examples/github-actions/umbrella-research.yml new file mode 100644 index 0000000..c7d8ff6 --- /dev/null +++ b/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.' diff --git a/examples/github-actions/url-to-markdown.yml b/examples/github-actions/url-to-markdown.yml new file mode 100644 index 0000000..56237ee --- /dev/null +++ b/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 diff --git a/openspec/changes/skills-distribution-growth/.openspec.yaml b/openspec/changes/skills-distribution-growth/.openspec.yaml new file mode 100644 index 0000000..8126432 --- /dev/null +++ b/openspec/changes/skills-distribution-growth/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-09 diff --git a/openspec/changes/skills-distribution-growth/design.md b/openspec/changes/skills-distribution-growth/design.md new file mode 100644 index 0000000..7fb40df --- /dev/null +++ b/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. diff --git a/openspec/changes/skills-distribution-growth/proposal.md b/openspec/changes/skills-distribution-growth/proposal.md new file mode 100644 index 0000000..e763ab7 --- /dev/null +++ b/openspec/changes/skills-distribution-growth/proposal.md @@ -0,0 +1,51 @@ +# Proposal: Make ReplyNodes skills discoverable and safely acquirable + +## Why now + +The canonical repository contains useful read-only public-data skills, but the live acquisition funnel is fragmented: + +- GitHub source has 23 `SKILL.md` files while the current Skills.sh page exposes 17 indexed entries. +- Skills.sh still renders legacy aliases and an old `replynodes/agent-skills` page. +- A 30-query live baseline found no ReplyNodes result for natural task-language queries; direct `replynodes` search does find the package. +- ClawHub has owner-scoped packages and aggregate counters, but aliases, source provenance, and attribution are not equivalent to GitHub source state. +- Focused CLI installation needs a clean-environment proof; the current host is at 99% disk usage and an install probe failed with `ENOSPC`. + +This change makes the source repository's public contract explicit, improves truthful task-language metadata, provides safe examples, and records external registry limitations without creating artificial installs or duplicate listings. + +## Goals + +1. Establish one canonical umbrella install and supported focused install form for priority skills. +2. Make README, root `SKILL.md`, taxonomy, and priority skill metadata task-oriented, bounded, read-only, and keyless-first only where verified. +3. Provide five copyable GitHub Actions examples that use harmless public reads and never expose credentials or create install loops. +4. Preserve a reproducible 30-query discovery baseline and daily measurement contract that separates registry counters from product attribution and retention. +5. Document Skills.sh and ClawHub as separate external artifacts and record owner actions required for index/provenance correction. + +## In scope + +- `README.md`, root `SKILL.md`, `skills.sh.json`, and priority skill first-screen metadata/CTAs. +- `docs/distribution-growth-plan.md`. +- Five files under `examples/github-actions/`. +- Baseline templates under `references/`. +- OpenSpec artifacts and deterministic distribution tests. + +## Out of scope + +- Registry publication, deletion, rename, hide/unhide, or duplicate listing creation. +- Synthetic installs, repeated CI installs, leaderboard manipulation, or new telemetry sinks. +- Credentials, cookies, private data, write-capable provider behavior, or changes to runtime APIs. +- Claiming a clean install or live registry refresh without readback evidence. + +## Capabilities + +- `install-discovery` +- `workflow-examples` +- `distribution-measurement` + +## Success criteria + +- Strict OpenSpec validation passes. +- Repository tests and `git diff --check` pass at the exact PR head. +- Public docs point to canonical source and focused pages, with legacy/index drift explicitly labeled. +- Baseline contains exactly 30 bounded query rows and preserves `not observable` when rank is unavailable. +- Clean focused and umbrella installation evidence is either captured or marked blocked with the actual host error; no partial install is reported as success. +- PR is opened against the repository default branch and the exact head SHA is reported. diff --git a/openspec/changes/skills-distribution-growth/specs/distribution-measurement/spec.md b/openspec/changes/skills-distribution-growth/specs/distribution-measurement/spec.md new file mode 100644 index 0000000..a1be869 --- /dev/null +++ b/openspec/changes/skills-distribution-growth/specs/distribution-measurement/spec.md @@ -0,0 +1,37 @@ +# Distribution measurement contract + +## ADDED Requirements + +### Requirement: Discovery baseline is reproducible +The repository MUST define exactly 30 realistic task-language queries with target slug, UTC timestamp, method, visibility, rank when observable, competitors, and evidence URL fields. + +#### Scenario: Unranked response +- **WHEN** a public search response has no ranked payload +- **THEN** rank is recorded as `not observable` +- **AND** the report does not infer a negative discovery result from missing rank + +#### Scenario: Direct brand query +- **WHEN** `replynodes` is searched directly +- **THEN** the evidence records the returned canonical and legacy listings separately +- **AND** it does not convert aggregate install counts into user identity or retention + +### Requirement: External and product metrics remain separate +Daily reporting MUST distinguish registry display counters from GitHub traffic, downstream callers, API-key conversion, sibling-skill adoption, and two-UTC-day retention. + +#### Scenario: External counter readback +- **WHEN** Skills.sh or ClawHub exposes an install/download counter +- **THEN** the value is recorded with exact URL, UTC timestamp, and source surface +- **AND** it is labeled an external display signal, never a genuine-user or retained-caller count + +#### Scenario: Attribution unavailable +- **WHEN** a registry does not expose source/referrer/identity or returns missing provenance +- **THEN** the field is recorded as `unavailable` +- **AND** the report does not invent causal attribution + +### Requirement: Owner actions are separate from source delivery +The plan MUST list Skills.sh indexing correction and ClawHub owner-scoped reconciliation as external actions, not as completed repository work. + +#### Scenario: Source merged but index stale +- **WHEN** the source PR is merged while a public registry still renders stale content +- **THEN** the status remains externally blocked until public readback changes +- **AND** no duplicate slug, forced version, or synthetic install is used as a workaround diff --git a/openspec/changes/skills-distribution-growth/specs/install-discovery/spec.md b/openspec/changes/skills-distribution-growth/specs/install-discovery/spec.md new file mode 100644 index 0000000..6220f44 --- /dev/null +++ b/openspec/changes/skills-distribution-growth/specs/install-discovery/spec.md @@ -0,0 +1,37 @@ +# Install and discovery contract + +## ADDED Requirements + +### Requirement: Canonical acquisition commands are explicit +The repository MUST document exactly one umbrella acquisition command and a direct focused-directory acquisition command for each priority skill. The documentation MUST identify the canonical GitHub source, the focused Skills.sh page when present, and the fact that external indexes may lag. + +#### Scenario: Umbrella install +- **WHEN** a user runs `npx --yes skills add replynodes/replynodes-agent-skills` in an isolated project +- **THEN** the documentation says the umbrella is the canonical all-skills path +- **AND** the user is not directed to a duplicate marketplace repository + +#### Scenario: Focused install +- **WHEN** a user wants `company-research`, `url-to-markdown`, or `app-store-api` +- **THEN** the documentation provides the direct `tree/main/skills/` command +- **AND** the command preserves the literal canonical slug and source repository + +#### Scenario: Nested-discovery compatibility +- **WHEN** the CLI is probed with a repository-plus-`--skill` form +- **THEN** the result is recorded as compatibility evidence only +- **AND** the primary CTA is not changed to a command that the current CLI cannot prove + +### Requirement: Clean-install evidence is honest +A clean-install record MUST include CLI version, isolated HOME/workdir, command, source SHA, installed path/content hash on success, or the exact failure and host blocker on failure. + +#### Scenario: Installation blocked by host +- **WHEN** installation fails with `ENOSPC`, network failure, or an upstream index error +- **THEN** the report records the literal error and marks the gate blocked +- **AND** it does not claim installation succeeded + +### Requirement: Metadata is task-oriented and bounded +Priority skill metadata MUST use truthful task language, bounded keywords, canonical slugs, and read-only/keyless-first claims only where supported by live evidence. + +#### Scenario: Legacy external slug +- **WHEN** Skills.sh or ClawHub renders a legacy alias +- **THEN** repository docs point to the canonical source/slug and classify the alias as external drift +- **AND** no duplicate listing or invented version is created diff --git a/openspec/changes/skills-distribution-growth/specs/workflow-examples/spec.md b/openspec/changes/skills-distribution-growth/specs/workflow-examples/spec.md new file mode 100644 index 0000000..52086bb --- /dev/null +++ b/openspec/changes/skills-distribution-growth/specs/workflow-examples/spec.md @@ -0,0 +1,29 @@ +# Workflow examples contract + +## ADDED Requirements + +### Requirement: Examples are copyable and read-only +The repository MUST provide five GitHub Actions examples covering company research, URL-to-Markdown, App Store research, umbrella routing, and scheduled public research. Each example MUST use bounded public inputs and document expected failure/rate-limit behavior. + +#### Scenario: Example discovery +- **WHEN** a developer opens an example +- **THEN** it names the canonical skill and links to the source repository and focused acquisition page +- **AND** it does not require a private credential merely to understand the install path + +#### Scenario: Safe execution +- **WHEN** an example executes a provider request +- **THEN** it uses a harmless public target, read-only GET path, and bounded timeout/retry behavior +- **AND** it does not claim private access, publishing, mutation, or unrestricted crawling + +#### Scenario: Secret safety +- **WHEN** a workflow needs optional authenticated enrichment +- **THEN** it references a GitHub secret by name without printing it +- **AND** logs and committed files contain no key, cookie, session, or bearer value + +### Requirement: Examples do not manufacture acquisition telemetry +The examples MUST NOT install a skill on every repository event, loop installs, star repositories, call marketplace mutation endpoints, or submit artificial discovery traffic. + +#### Scenario: Manual or scheduled use +- **WHEN** a workflow is triggered +- **THEN** it is manual or explicitly scheduled and bounded +- **AND** the workflow does not present execution as an install/download conversion diff --git a/openspec/changes/skills-distribution-growth/tasks.md b/openspec/changes/skills-distribution-growth/tasks.md new file mode 100644 index 0000000..1034218 --- /dev/null +++ b/openspec/changes/skills-distribution-growth/tasks.md @@ -0,0 +1,14 @@ +# Tasks + +- [ ] 1.1 Pin the canonical source SHA and record the live GitHub, Skills.sh, skills CLI, and ClawHub URLs/statuses used by this change. +- [ ] 1.2 Preserve exactly 30 realistic discovery queries in `references/discovery-query-baseline.csv`; record observed results, `not observable` ranks, competitors, and unavailable attribution fields without synthetic searches/install loops. +- [ ] 1.3 Document the umbrella command and direct focused-directory commands for `company-research`, `url-to-markdown`, `brand-kit`, and `app-store-api`; document repository-plus-`--skill` as compatibility-only where applicable. +- [ ] 1.4 Update README, root `SKILL.md`, `skills.sh.json`, and priority skill metadata with bounded task language, canonical slugs, read-only/keyless-first claims, and external-index caveats. +- [ ] 1.5 Add five copyable GitHub Actions examples covering company research, URL-to-Markdown, App Store research, umbrella routing, and scheduled public research; ensure no install loop, mutation, credential logging, or private-data claim. +- [ ] 1.6 Define the daily measurement template separating external counters, GitHub traffic, downstream product attribution, and two-UTC-day retention; keep pending/unavailable states explicit. +- [ ] 1.7 Run `openspec validate skills-distribution-growth --strict`, `openspec status --change skills-distribution-growth`, `git diff --check`, and repository distribution tests. +- [ ] 1.8 Run focused and umbrella install probes in a clean HOME only after host disk prerequisites pass; record source SHA, installed paths, content hashes, or the literal blocker. Internal probes MUST set `DISABLE_TELEMETRY=1`. +- [ ] 1.9 Run safe keyless smoke/readback for each documented public route without credentials, and preserve status/content-type/rate-limit evidence where exposed. +- [ ] 1.10 Review the exact PR head independently; verify changed-file scope, base/head SHA, and no secret or artificial telemetry path. +- [ ] 1.11 Open upstream correction requests only as separate owner actions for stale Skills.sh indexing and ClawHub alias/provenance state; do not create duplicate listings in this PR. +- [ ] 1.12 After merge, read back GitHub, Skills.sh, and ClawHub separately and start the observation window only from a verified post-merge UTC date; do not archive this change before implementation and acceptance evidence are complete. diff --git a/references/discovery-query-baseline.csv b/references/discovery-query-baseline.csv new file mode 100644 index 0000000..683bdab --- /dev/null +++ b/references/discovery-query-baseline.csv @@ -0,0 +1,31 @@ +query,target_slug,observed_at_utc,method,visible,rank,evidence_url,competitors,notes +company profile,company-research,,,,,,, +business intelligence company research,company-research,,,,,,, +company research by domain,company-research,,,,,,, +prospect research company,company-research,,,,,,, +account research brief,company-research,,,,,,, +vendor due diligence snapshot,company-research,,,,,,, +first party company brief,company-research,,,,,,, +public company intelligence ai agent,company-research,,,,,,, +url to markdown,url-to-markdown,,,,,,, +webpage to markdown,url-to-markdown,,,,,,, +article to markdown for llm,url-to-markdown,,,,,,, +html to markdown clean,url-to-markdown,,,,,,, +read a docs page as markdown,url-to-markdown,,,,,,, +extract webpage for rag,url-to-markdown,,,,,,, +clean web context from url,url-to-markdown,,,,,,, +iOS app search,app-store-api,,,,,,, +App Store reviews API,app-store-api,,,,,,, +Apple app ratings research,app-store-api,,,,,,, +App Store privacy details,app-store-api,,,,,,, +find apps by developer iPhone,app-store-api,,,,,,, +similar apps App Store,app-store-api,,,,,,, +public web research for agents,replynodes,,,,,,, +no key web research,replynodes,,,,,,, +research SaaS competitors,competitor-research,,,,,,, +current product research from website,company-research,,,,,,, +RAG public webpage extraction,url-to-markdown,,,,,,, +read-only App Store data,app-store-api,,,,,,, +agent skill company enrichment,company-research,,,,,,, +public research workflow AI agent,replynodes,,,,,,, +read public data without API keys,replynodes,,,,,,, diff --git a/references/distribution-daily-baseline.csv b/references/distribution-daily-baseline.csv new file mode 100644 index 0000000..d622df0 --- /dev/null +++ b/references/distribution-daily-baseline.csv @@ -0,0 +1 @@ +date_utc,source_sha,skills_sh_installs_external,clawhub_downloads_external,clawhub_installs_external,github_stars,github_views_14d,github_clones_14d,github_referrers,api_distinct_callers,api_requests,api_key_created_after_use,two_day_retained_callers,attribution_sources,readback_urls,notes diff --git a/skills.sh.json b/skills.sh.json index 549ec5f..344b18e 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -4,7 +4,7 @@ "groupings": [ { "title": "Research", - "description": "ReplyNodes read-only web, brand, app-store, video, and community research for AI agents.", + "description": "ReplyNodes keyless, read-only public web research for AI agents — web search and scraping, URL to Markdown, company research, competitor and competitive analysis, and Apple App Store data.", "skills": [ "replynodes", "company-research", @@ -15,7 +15,7 @@ }, { "title": "Brand research", - "description": "ReplyNodes read-only brand discovery, identity, styleguide, and typography research.", + "description": "ReplyNodes keyless, read-only brand research for AI agents — brand discovery, identity, public logos, colors, fonts, styleguide, typography, and design tokens.", "skills": [ "brand-kit" ] diff --git a/skills/app-store-api/SKILL.md b/skills/app-store-api/SKILL.md index ec97b75..b600541 100644 --- a/skills/app-store-api/SKILL.md +++ b/skills/app-store-api/SKILL.md @@ -1,6 +1,12 @@ --- name: app-store-api -description: "Apple App Store API for agents: search iOS apps by term, read ratings and reviews, look up apps by id, list developer apps, read privacy details, and find similar apps. Free keyless first request; read-only, with authenticated continuation." +description: >- + Apple App Store API for AI agents: search iOS apps by keyword, read ratings + and reviews, look up an app by id, list a developer's apps, read privacy + details, and find similar apps. Use it for App Store research, iOS app + discovery, ASO (app store optimization), competitor app and review analysis, + and developer catalog lookups. Free keyless first request, read-only, with + an optional authenticated continuation. license: MIT compatibility: "Free and keyless for the first request (network access only; shared anonymous quota, Tier B: 10 admitted requests per trusted client-IP bucket per capability per UTC day; no account or API key). Authenticated continuation needs an API client or MCP-capable agent and REPLYNODES_API_KEY in a secret store; an existing authenticated free account has 500 credits." metadata: @@ -9,7 +15,8 @@ metadata: version: "1.0.0" endpoint: https://api.replynodes.com mcp_endpoint: https://mcp.replynodes.com/mcp - keywords: [App Store API, iOS app search, app reviews, app ratings, app developer, app privacy, similar apps, iTunes] + repository: https://github.com/replynodes/replynodes-agent-skills + keywords: [App Store API, iOS app search, App Store search, app reviews, app ratings, app developer, app privacy, similar apps, iTunes API, ASO, app store optimization, competitor apps, iOS, keyless] --- # ReplyNodes Apple App Store API @@ -130,7 +137,7 @@ This skill was renamed from `app-store-research` (agent-skills issue #57, canonical taxonomy #56). Install the canonical slug: ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill app-store-api --full-depth +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/app-store-api ``` The previous `--skill app-store-research` install name is superseded by diff --git a/skills/brand-kit/SKILL.md b/skills/brand-kit/SKILL.md index 6e1be3b..6d2d89e 100644 --- a/skills/brand-kit/SKILL.md +++ b/skills/brand-kit/SKILL.md @@ -1,6 +1,12 @@ --- name: brand-kit -description: "Brand Kit API for agents: get a company's existing public brand identity from a domain — logos, colors, fonts, typography, and provenance — as zero-auth JSON. Read-only; no brand generation." +description: >- + Brand Kit API for AI agents: get a company's existing public brand identity + from a domain — logos, colors, fonts, typography, styleguide, and provenance + — as zero-auth JSON. Use it to build a branded landing page, deck, report, + or dashboard, fetch brand assets and design tokens, or extract a visual + identity from a public website. Free, keyless, read-only; it retrieves + existing public signals and does not generate a brand. license: MIT compatibility: "Network access only for the free zero-auth brand host. An optional authenticated MCP route needs an MCP-capable agent and REPLYNODES_API_KEY in a secret store." metadata: @@ -9,7 +15,7 @@ metadata: version: "1.0.0" endpoint: https://brand.replynodes.com mcp_endpoint: https://mcp.replynodes.com/mcp - keywords: [brand kit, brand assets, logo, colors, fonts, typography, styleguide, design tokens, domain] + keywords: [brand kit, brand assets, brand identity, brand guidelines, logo, logos, colors, fonts, typography, styleguide, design tokens, visual identity, domain, brand lookup] --- # Brand Kit @@ -131,7 +137,7 @@ simple single-domain identity fetch through MCP. ## Install and first use ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill brand-kit --full-depth +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/brand-kit curl --fail-with-body https://brand.replynodes.com/replynodes.com.json ``` diff --git a/skills/company-research/SKILL.md b/skills/company-research/SKILL.md index 39d6524..f130d6b 100644 --- a/skills/company-research/SKILL.md +++ b/skills/company-research/SKILL.md @@ -1,6 +1,13 @@ --- name: company-research -description: "Free company research for AI agents: give it a company domain and get a cited company brief — what it does, products, pricing, target market, integrations, and key pages — from first-party evidence, with no API key and no signup." +description: >- + Free, keyless company research and business intelligence for AI agents: give + it a company domain and get a cited company brief — what the company does, + its products, pricing, target market, customers, integrations, and important + pages — grounded in first-party evidence. No API key, no signup, no account. + Use it for a company profile, account or prospect research, vendor + evaluation, and a bounded due-diligence snapshot, with honest unknowns + instead of guesses. license: MIT compatibility: "Free and keyless for the domain-to-brief path (network access only). Runs in any Agent Skills-compatible host — Claude Code, Codex, Cursor, Windsurf, OpenClaw. Optional deeper MCP enrichment needs an MCP-capable agent and REPLYNODES_API_KEY in a secret store." metadata: @@ -8,6 +15,8 @@ metadata: author: ReplyNodes version: "2.0.0" endpoint: https://mcp.replynodes.com/mcp + repository: https://github.com/replynodes/replynodes-agent-skills + keywords: [company research, company profile, company brief, business intelligence, domain research, account research, prospect research, sales prospecting, vendor evaluation, due diligence, company enrichment, competitive research, first-party evidence, keyless] --- # Free Company Research & Business Intelligence diff --git a/skills/competitor-research/SKILL.md b/skills/competitor-research/SKILL.md index a2ad201..8b5bee1 100644 --- a/skills/competitor-research/SKILL.md +++ b/skills/competitor-research/SKILL.md @@ -1,6 +1,12 @@ --- name: competitor-research -description: "Competitor research for agents: build a sourced, read-only comparison from verified public company domains — official sites, brand identity, apps, and community signals — with honest unknowns." +description: >- + Competitor research and competitive analysis for AI agents: build a sourced, + read-only comparison from verified public company domains — official sites, + brand identity, mobile apps, and community signals — with honest unknowns. + Use it for alternatives and side-by-side comparison research, competitive + intelligence, market and landscape research, and positioning a product + against named competitors when you have a real domain for each. license: MIT compatibility: "Known-domain Markdown and Brand reads need only network access (free, zero-auth, Tier A: 20 requests/UTC day per capability), and the reviewed `/v1` web-search, single-page scrape, app-store, Google Play, Reddit, and YouTube reads are free keyless at Tier B (10/UTC day per capability). Deeper authenticated routes (site map/crawl, brand search/retrieve, Hacker News, MCP) need an MCP-capable agent or API client and REPLYNODES_API_KEY in a secret store; an existing authenticated free account has 500 credits." metadata: @@ -8,7 +14,7 @@ metadata: author: ReplyNodes version: "1.0.0" endpoint: https://mcp.replynodes.com/mcp - keywords: [competitor research, alternatives, competitor analysis, market research, comparison, public domains] + keywords: [competitor research, competitor analysis, competitive analysis, competitive intelligence, alternatives, comparison, market research, competitive landscape, public domains] --- # ReplyNodes competitor research @@ -24,7 +30,7 @@ does not contact companies, publish content, or modify provider data. For each verified bare domain, start with the free, zero-auth paths (no key): ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill competitor-research --full-depth +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/competitor-research curl --fail-with-body 'https://md.replynodes.com/https://replynodes.com/' curl --fail-with-body 'https://brand.replynodes.com/replynodes.com.json' ``` diff --git a/skills/google-play-api/SKILL.md b/skills/google-play-api/SKILL.md index 46a47b2..3e7b645 100644 --- a/skills/google-play-api/SKILL.md +++ b/skills/google-play-api/SKILL.md @@ -134,7 +134,7 @@ This internal skill was renamed from `google-play-research` (agent-skills issue #57, canonical taxonomy #56). The canonical install slug is `google-play-api`: ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill google-play-api --full-depth +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/google-play-api ``` Registry-side redirects and readback are owned by issue #58. diff --git a/skills/pdf-to-markdown/SKILL.md b/skills/pdf-to-markdown/SKILL.md index cf4112c..1aaf460 100644 --- a/skills/pdf-to-markdown/SKILL.md +++ b/skills/pdf-to-markdown/SKILL.md @@ -84,7 +84,7 @@ authoritative. Install this focused skill from the canonical source: ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill pdf-to-markdown +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/pdf-to-markdown ``` Canonical source: https://github.com/replynodes/replynodes-agent-skills diff --git a/skills/reddit-api/SKILL.md b/skills/reddit-api/SKILL.md index 08b92ed..5c9cfee 100644 --- a/skills/reddit-api/SKILL.md +++ b/skills/reddit-api/SKILL.md @@ -127,7 +127,7 @@ This internal skill was renamed from `reddit-research` (agent-skills issue #57, canonical taxonomy #56). The canonical install slug is `reddit-api`: ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill reddit-api --full-depth +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/reddit-api ``` A ClawHub `reddit-api` package already exists as external registry state; it is diff --git a/skills/url-to-markdown/SKILL.md b/skills/url-to-markdown/SKILL.md index aa2bd3f..7a3c1a5 100644 --- a/skills/url-to-markdown/SKILL.md +++ b/skills/url-to-markdown/SKILL.md @@ -1,6 +1,11 @@ --- name: url-to-markdown -description: "Fetch a public webpage as clean Markdown for LLM context: read, summarize, quote, or cite any public URL while preserving the exact source URL. Free, zero-auth, read-only." +description: >- + Fetch a public webpage as clean Markdown for LLM and RAG context: read, + scrape, summarize, quote, or cite any public URL while preserving the exact + source URL. Use it to convert an article, docs page, blog post, or product + page into compact Markdown, strip cookie banners and navigation clutter, or + feed a web page into an LLM. Free, zero-auth, keyless, and read-only. license: MIT compatibility: "Network access only. The Markdown host is free and zero-auth; no account, API key, or MCP connection is needed." metadata: @@ -9,7 +14,7 @@ metadata: version: "1.1.0" repository: https://github.com/replynodes/replynodes-agent-skills endpoint: https://md.replynodes.com - keywords: [web, markdown, URL, LLM context, agent, read, webpage to markdown, scrape page] + keywords: [web, markdown, url, llm context, rag, webpage to markdown, html to markdown, scrape page, extract text, read url, web page reader, article to markdown, agent, read] --- # URL to Markdown diff --git a/skills/youtube-api/SKILL.md b/skills/youtube-api/SKILL.md index a50a5b5..f61a17b 100644 --- a/skills/youtube-api/SKILL.md +++ b/skills/youtube-api/SKILL.md @@ -126,7 +126,7 @@ This internal skill was renamed from `youtube-research` (agent-skills issue #57, canonical taxonomy #56). The canonical install slug is `youtube-api`: ```bash -npx skills add https://github.com/replynodes/replynodes-agent-skills --skill youtube-api --full-depth +npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/youtube-api ``` A ClawHub `youtube-public-api` package exists as external registry state; it is diff --git a/tests/test-distribution.sh b/tests/test-distribution.sh index 05e7623..bc34d83 100755 --- a/tests/test-distribution.sh +++ b/tests/test-distribution.sh @@ -6,12 +6,16 @@ import json import re import sys from pathlib import Path +import csv root = Path(sys.argv[1]).resolve() readme = (root / "README.md").read_text(encoding="utf-8") distribution = (root / "references/company-research-distribution.md").read_text(encoding="utf-8") skill = (root / "skills/company-research/SKILL.md").read_text(encoding="utf-8") taxonomy = json.loads((root / "skills.sh.json").read_text(encoding="utf-8")) +baseline_path = root / "references/discovery-query-baseline.csv" +with baseline_path.open(newline="", encoding="utf-8") as handle: + baseline = list(csv.DictReader(handle)) FOCUSED_CTA = "npx skills add https://github.com/replynodes/replynodes-agent-skills/tree/main/skills/company-research" @@ -21,9 +25,20 @@ assert FOCUSED_CTA in readme assert FOCUSED_CTA in distribution assert FOCUSED_CTA in skill assert "npx skills add replynodes/replynodes-agent-skills" in readme -# The repository-plus-`--skill` form is only a documented compatibility limitation. assert "--skill company-research --full-depth" not in readme assert "company-research-distribution.md" in readme +assert len(baseline) == 30, f"discovery baseline must contain 30 rows, found {len(baseline)}" +assert len({row["query"] for row in baseline}) == 30, "discovery queries must be unique" +assert all(row["target_slug"] for row in baseline), "every discovery query needs a target slug" + +examples = sorted((root / "examples/github-actions").glob("*.yml")) +assert len(examples) == 5, f"expected five workflow examples, found {len(examples)}" +for example in examples: + text = example.read_text(encoding="utf-8") + assert "npx --yes skills add" not in text.replace("# npx --yes skills add", ""), ( + f"{example.name} must not run a recurring install" + ) + assert "https://github.com/replynodes/replynodes-agent-skills" in text assert "PENDING" in distribution assert re.search(r"two\s+separate UTC calendar days", distribution) assert "owner-IP" in distribution