skills-sh-growth-loop

name

skills-sh-growth-loop

description

Measure Agent Skill discoverability and install telemetry on skills.sh, track deduplicated evidence of verified organic users, correlate community campaigns with outcomes, render shareable scorecards, and choose the next ethical growth experiment. Use when an agent needs to monitor skills.sh indexing or search rank, grow a skill to a user target, promote skills through Reddit or another community without spamming, evaluate post/comment feedback, or decide which skill improvement to test next.

Skills.sh Growth Loop

Run a measured loop: baseline discovery, make one community-specific experiment, observe outcomes, record explicit user evidence, and improve the skill. Never turn the loop into unattended posting or engagement automation.

Set up the campaign

Create a target file using the schema in references/data-contracts.md. Keep runtime state in an untracked operator-owned directory. Resolve the folder containing this SKILL.md once; do not assume the caller's current working directory is the skill.

GROWTH_SKILL_DIR=/absolute/path/to/skills-sh-growth-loop

node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" monitor \
  --targets /absolute/path/to/targets.json \
  --state /absolute/path/to/private-state \
  --out /absolute/path/to/report

monitor is a one-shot scheduler-friendly cycle: it takes one observation per target, renders the report with that exact timestamp, compares the new registry state with the prior snapshot, and evaluates campaign ready. Schedule it through operator-owned automation if desired. The skill itself never creates a scheduler, posts, replies, votes, or treats a suggested action as write authorization. A monitor cycle may append metrics.jsonl and replace derived report artifacts; it must not mutate campaign, engagement, or evidence ledgers.

Each monitor/report writes aggregate Markdown/JSON/SVG artifacts plus one source-qualified 1200×630 SVG under <out>/skill-cards/ for every target. Treat these as dated GTM status cards, not capability proof, download attribution, or permission to post. Only the exact campaignCandidate may receive an ELIGIBLE EXPERIMENT badge, and only after the global campaign gate is ready. Its card asks for one real task plus an explicit installed-and-ran report and one friction point; it never asks for an upvote. Cards for missing indexing, cooldown, pending observation, or negative signals must visibly remain repair/wait/pause artifacts. Never publish a generated card automatically.

For an independent installed-copy evaluation, use one public skill you genuinely want to assess. Replace only owner/repo@skill-slug in this prompt with the exact source and slug of a public skill the tester genuinely wanted to inspect. Resolve the installed skill directory and run its bundled one-target helper:

node "$GROWTH_SKILL_DIR/examples/monitor-public-skill.mjs" owner/repo@skill-slug

The helper validates exactly one public owner/repo@skill-slug, runs the production monitor command once, and prints one compact JSON line. It writes local metrics and report artifacts only inside a private temporary directory and removes that directory before exit; it does not install another skill, write to skills.sh, or write to a social platform. Do not post or reply. Return the matching exact compact success shape:

{"ok":true,"command":"monitor","snapshot":{"targetCount":1,"indexedCount":1,"missing":[]}}

{"ok":true,"command":"monitor","snapshot":{"targetCount":1,"indexedCount":0,"missing":["skill-slug"]}}

Both are successful monitor runs because ok:true and command:"monitor" are present. indexedCount:0 with a populated missing array reports a registry result, not a command failure. Live rank, observed-install counts, and timestamps vary and are deliberately omitted from this compact handoff. After the run, submit only the compact ok, command, and snapshot summary—or one sanitized error—through the structured tester report. Select Installed and ran only for your own non-internal run; install-only, failed, copied, or simulated results are feedback rather than verified organic use.

Treat observedInstalls as registry telemetry. Do not call it an organic user, conversion, or attributed download. Count progress toward the user goal only from deduplicated, explicit installed-and-ran evidence recorded through the appropriate evidence gate.

Protect the registry signal during maintainer and CI checks. Prefix every diagnostic skills add, skills list, or real-install smoke test with DO_NOT_TRACK=1. Do not assume CI=1 disables telemetry: skills 1.5.22 still sends the event and only tags it ci=1 unless DO_NOT_TRACK or DISABLE_TELEMETRY is set. Never seed a missing catalog entry with an owner, teammate, subagent, or CI install; wait for a genuinely independent user whose test has real value to them.

Run one promotion experiment

1. Select one under-goal skill and one community whose current rules permit the exact post type. Prefer a weekly showcase or self-promotion thread when rules direct projects there.
2. Research the community before drafting. When Reddit skills are available, run scout, requirements, and voice/read steps first. Read the current rule text; the absence of a prohibition is not blanket permission.
3. Lead with a useful finding, reproducible demo, benchmark, or failure analysis. Disclose that you maintain the project, state whether it is free, and say what kind of feedback would change the skill.
4. Attach a real screenshot, short capture, or the generated scorecard. Redact usernames, profile paths, cookies, and identifiers. Do not use fabricated testimonials or metrics.
5. Make every write a dry-run first. Inspect the exact title, body, destination, flair, and content hash. Perform the live write only through a tool that has an explicit confirmation gate.
6. Verify visibility after the write. Record live only when the post survives moderation and is publicly readable. Do not immediately repost a filtered or removed submission.
7. Add the experiment to the local ledger:

node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" campaign add \
  --state /absolute/path/to/private-state \
  --skill reddit-scout \
  --kind post \
  --url https://www.reddit.com/r/example/comments/id/post/ \
  --community r/example \
  --status live \
  --hypothesis "A rules-first CLI trace earns three qualified testers" \
  --rules-url https://www.reddit.com/r/example/about/rules \
  --rules-checked-at 2026-08-07T00:00:00Z \
  --disclosed true \
  --dry-run-reviewed true \
  --content-file /absolute/path/to/published-body.md

Never automate votes, request upvotes, use multiple accounts, send unsolicited bulk replies, or repeat identical/substantially similar posts across communities.

Observe and reply

Use the community tool's read-only command to fetch the public permalink. Normalize each observation to the engagement contract, then ingest it through stdin:

node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" campaign ingest \
  --state /absolute/path/to/private-state < observation.json

Reply only to a real question or correction. Answer directly, disclose material affiliation when relevant, and do not manufacture a conversation. Let at least one experiment reach its planned observation window before opening another community.

Check the machine gate before drafting or approving the next live experiment:

node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" campaign ready \
  --state /absolute/path/to/private-state

The default window is 72 hours. ready: true requires elapsed time plus an observation both observed and ingested at or after the deadline. The CLI timestamps mutations from its wall clock, rejects mutation-time --at, and rejects future observations. An early visibility check does not close the window, and campaign add --status live enforces the same gate under an exclusive state lock. Legacy observations without a trusted ingestedAt require a fresh observation.

Record an organic user only when a human explicitly reports installing and running the named skill for that person's own purpose. Use a stable opaque key, not a username or email:

node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" evidence add \
  --state /absolute/path/to/private-state \
  --skill reddit-scout \
  --kind reddit-comment \
  --reference https://www.reddit.com/r/example/comments/id/post/comment/ \
  --user-key tester-opaque-07 \
  --verified true \
  --organic true \
  --internal false

The CLI hashes user-key before storage. Never count teammates, CI installs, the operator's own tests, duplicate identities, inferred lurkers, stars, or upvotes as verified organic users.

For a structured GitHub tester-report issue, do not use generic evidence add. Produce the normalized packet defined in references/data-contracts.md from a current read-only GitHub observation and explicit operator roster review. Preview it first:

trusted-read-only-review-producer | node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" \
  evidence github-review --targets /absolute/path/to/targets.json \
  --state /absolute/path/to/private-state

Only if the preview is eligible, repeat that exact fresh packet with --write --confirm sha256:PREVIEW_DIGEST. The digest binds the reviewed issue revision, claims, selected target policy, physical state path, and eligibility blockers. The numeric GitHub account ID is accepted only inside stdin, hashed in memory, and never printed or stored. Trust boundary: the CLI validates the trusted normalized review packet; it does not independently fetch GitHub or prove the form answers. A later issue edit, deletion, visibility change, or label change requires a fresh public read and human review.

Turn feedback into a skill change

Prefer a change when feedback is reproducible, independently repeated, or exposes a safety/accuracy defect. Keep praise and raw engagement from outweighing a concrete failure. Make the smallest testable change, validate the skill, publish it through its own repository, then annotate the next experiment with the changed hypothesis.

Use the report's registry prioritySkill for indexing/packaging work and its campaignCandidate for promotion research. The latter rotates indexed, under-goal skills with fewer completed experiments before repeats; it is still a queue, not an order to post. Search regressions, privacy changes, rule changes, cooldown windows, or negative community signals override both suggestions.

Read the contracts before extending the loop

• Read references/data-contracts.md when producing target, engagement, or evidence records.
• Read references/measurement.md when interpreting skills.sh metrics, campaign attribution, or the organic-user goal.
• Read references/publication.md before treating a GitHub default-branch change as a skills.sh release or installed-copy update.

Run node "$GROWTH_SKILL_DIR/scripts/gtm-loop.mjs" --help for the command surface.