agentleFS
Pupok462Pupok462/open-geo/.claude/skills/semantic-core/SKILL.md

semantic-core

Skill28 starsChanged 23 days agoMITView on GitHub

Build a measured semantic core for a brand through official keyword APIs (Yandex Wordstat for RU, Google Ads Keyword Planner / Bing Webmaster worldwide, autocomplete everywhere), commit it as core.json plus a questions.csv, and hand that straight to an open-geo visibility run. Use when the user wants demand research, a semantic core, keyword volume, or "collect the questions and then measure visibility" — no browser and no manual keyword tool.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. awaik/direct-mcp-ai-project★ 20same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Ask only for what is still unknown: geo(s), query language(s), count, split, and — unless --no-run — the engine and worker count for the …

    line 69
  2. Very specific:

    keep every cluster's phrases attached — the anchor phrase's scope becomes the signal of every question that cluster ships.

    line 125
  3. Very specific:

    Write the synthesized SemanticCore object (INTERFACES §8.3) to a UTF-8 temp file, then:

    line 138
  4. Very specific:

    Read stdout {core, questions_csv, clusters, written, by_lens, coverage, errors}.

    line 148

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Purpose

semantic-core — measured demand core, then the run

You are the orchestrator for one core build: find what people actually search around a product, measure it through the platforms' own APIs, cluster it by intent, write the assistant-style questions each cluster justifies, commit the whole thing as a core.json + questions.csv, and hand that to an open-geo visibility run.

Two halves, deliberately separated:

  • Deterministic — the numbers. demand/ asks Wordstat / Google Ads / Bing / autocomplete and returns each figure with its scope (region, period, pull date). No browser, no logged-in session, no hand-typed volume. Contract: pipeline/INTERFACES.md §8, guide: demand/README.md.
  • Agentic — the judgement. Which angles the product has, how a person phrases the need to an assistant, which lines survive a skeptic. Authority: harvest/METHODOLOGY.md (§3 demand gate, §4 lens invariants, §5 segments).

Run Python from the open-geo runtime root with its venv (.venv/bin/python). Code and intermediate JSON are English; the summary you print follows --lang.

Ask / Spawn. Prefer the host's structured question API (AskUserQuestion on Claude Code); otherwise ask in the conversation with enumerated options and wait. Fan out workers with the host's native spawn (Claude Code Agent tool, all in one message; Grok spawn_subagent with subagent_type; Codex/Cursor/Gemini — that host's equivalent). Never guess a required value.


INVOCATION

/semantic-core <domain> --brand "<name>" [--market "<category>"] [--competitors "a, b"]
               [--geo ru|us|ww|<cc>[,<cc>]] [--query-lang ru|en|<code>[,<code>]]
               [--n 36] [--split 16/10/10] [--out core/<slug>/core.json]
               [--run <engine>] [--n-worker N] [--output data|dashboard|pdf|both]
               [--lang en|ru|zh|ar] [--no-run]
arg / flagrequireddefaultmeaning
<domain>yes—The product's site. Also the target of the follow-on run.
--brand "<name>"yes—Human brand name; enforces the lens/brand invariants at commit time.
--marketnoinferredCategory in the user's words. Inferred from the homepage when absent — always echo the inference for confirmation.
--competitorsno—Seed list; workers extend it.
--geonoruISO-3166 alpha-2 lowercase, or ww for worldwide. Comma-separated for several markets — each is measured on its own ruler.
--query-langnofollows geoThe language people search in — independent of --lang (the deliverable language). A distinct language is a distinct slice with its own CSV.
--nno36Target questions across all slices.
--splitnoderivedgeneral/branded/comparative, general-tilted (for 36: 16/10/10).
--outnocore/<brand-slug>/core.jsonWhere the core artifact lands. The CSV goes beside it as <brand-slug>_questions.csv.
--run <engine>noaskEngine for the follow-on open-geo run (google, chatgpt_search, yandex_neuro, …).
--n-workernoaskCapture concurrency for that run.
--no-runnooffBuild and commit the core, stop before the run.

Missing required values go to STEP 1 (wizard), never to a guess.


STEP 1 — RESOLVE PARAMETERS

  1. Take everything from the invocation. If <domain> or --brand is missing, ask for them (Ask), one compact question per unknown.
  2. Fetch the homepage (WebFetch) to infer market/category and obvious competitors. Echo the inference in one line and let the user correct it — a wrong category poisons every seed.
  3. Ask only for what is still unknown: geo(s), query language(s), count, split, and — unless --no-run — the engine and worker count for the follow-on run.

STEP 2 — CAPABILITY CHECK (what can actually be measured)

For each geo:

.venv/bin/python -m demand.doctor --geo <cc>

Report the verdict in one line per geo:

  • volume available — proceed; the core will rest on numbers.
  • presence only — no volume ruler is configured for that locale. Say exactly which credential is missing and what it unlocks (the doctor prints the steps), then ask whether to (a) proceed presence-only — a core grounded in real autocomplete phrasings but without volume, every line marked as such, or (b) pause while the user obtains the key. Never silently downgrade, and never fabricate a number to fill the gap.

Carry the verdict into every worker brief: it decides which gate the workers are working under (METHODOLOGY §3).

STEP 3 — SEEDS AND SEGMENTS

  1. Root phrases (5–12): the job the product does, in the words of the market — not the brand's marketing words. Derive from the homepage, the category, and competitor positioning.
  2. Segments (METHODOLOGY §5), derived from the product, not a fixed list: demand-primary, demand-secondary, category/discovery, branded-reputation, comparative-rivals, plus supply-side for a two-sided product and a per-language slice where a real audience exists.
  3. Sanity-check the roots before fanning out — one cheap call each:
    .venv/bin/python -m demand.lookup --geo <cc> --lang <code> --phrase "<root>" --related 10
    A root with zero demand is a wrong root: fix it here, not in five workers at once.

STEP 4 — FAN OUT (one core-worker per segment, in parallel)

Spawn one core-worker sub-agent per segment using Spawn, concurrently. Its contract lives in ../../agents/core-worker.md — do not restate it. Each brief carries: the product context, its one segment + dominant lens, the geo/language and the doctor verdict, its worker index, the seeds relevant to it, and its target (2–4 clusters, 6–15 measured phrases, 4–10 questions).

A core-worker measures through demand/, phrases the questions, and returns a CoreCluster JSON array. It never writes the core, the CSV, or the DB, and never opens a browser.

STEP 5 — SYNTHESIZE (you)

Merge every worker's clusters and:

  • drop unmeasured clusters — no phrase with a provider + scope means no evidence; do not rescue it by writing a number yourself;
  • dedup by meaning across segments (not just by string), keeping the strongest evidence;
  • balance to --split with the general-tilt, maximizing intent diversity inside each lens — the GEO opening lives in general, where people do not yet know the brand;
  • split by language: each query language becomes its own slice and its own CSV;
  • keep every cluster's phrases attached — the anchor phrase's scope becomes the signal of every question that cluster ships.

STEP 6 — SKEPTIC PASS

Spawn 1–2 harvest-skeptic sub-agents using Spawn (contract in ../../agents/harvest-skeptic.md) with the thesis and the final {query, lens} list. Apply the cuts, backfill each from the next-strongest candidate in the same cluster, and re-run until every shipped line survives. The skeptic cuts unmeasured lines and lines that overstate a presence-only signal — both are failures of this step, not of the worker.

STEP 7 — COMMIT THE CORE

Write the synthesized SemanticCore object (INTERFACES §8.3) to a UTF-8 temp file, then:

.venv/bin/python -m demand.core \
  --out core/<slug>/core.json \
  --questions-out core/<slug>/<slug>_questions.csv \
  --brand "<name>" --domain <domain> --rationale core/<slug>/<slug>_rationale.md \
  < /tmp/open_geo_core_final.json

Read stdout {core, questions_csv, clusters, written, by_lens, coverage, errors}. errors must be empty — the usual causes are a mislabeled lens (general naming the brand, branded not naming it) and an unmeasured cluster. Fix and re-run until errors: []. For a second query language, call it again with its own --out / --questions-out.

Then write <slug>_rationale.md yourself: per cluster — who we catch, on which measured signals (quote the scope strings), why this lens, which competitors surfaced. This is the provenance the CSV omits.

STEP 8 — REVIEW GATE (human-in-the-loop)

Show: total questions, by_lens, coverage (how many phrases rest on volume vs presence), the strongest and weakest clusters by measured volume, and the full query list. Ask (Ask): Apply / Edit (adjust rows, re-run STEP 7 until errors: []) / Discard. Never go straight to capture on a freshly generated set without the operator seeing it.

STEP 9 — HAND OFF TO THE RUN

Unless --no-run, invoke the open-geo skill with the committed artifacts:

/open-geo <questions_csv> <engine> <domain> --brand "<name>" --n-worker <N> \
          [--output …] [--lang …]

core.json is the carrier: it records questions_csv, brand, domain and totals.coverage, so the run reads one file and cannot mismatch the set it measures. open-geo takes its STEP A.5 fast path — a committed core and a hand-made CSV are indistinguishable downstream.

Finish with a short summary in --lang: where core.json and the CSV are, questions by lens, coverage (volume vs presence), which providers answered, and the run that was started (or the exact command to start it later).

Boundaries

  • Numbers come from demand/; judgement comes from you and the workers. Neither substitutes for the other.
  • Never invent a volume, and never present a presence-only signal as measured demand.
  • The commit path is demand.core → harvest.build: same CSV invariants as every other question set in this project. Nothing downstream of the CSV changes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.