agentleFS
dbclsdbcls/togomcp/.claude/skills/intro-page-updater/SKILL.md

intro-page-updater

Skill21 starsChanged 2 months agoMITView on GitHub

Update the public TogoMCP intro/landing page at `togo_mcp/data/docs/togomcp-intro.html` whenever the catalog of databases, the catalog of MCP tools, or any other surface fact shown on the page changes. Trigger when the user adds/removes/renames a database (MIE file, `endpoints.csv` row), adds/removes/renames a tool (any `@mcp.tool` decorator in `togo_mcp/*.py`), updates the preprint citation, changes setup instructions for a host (Claude/ChatGPT/Gemini), revises the recommended companion MCP servers, or otherwise edits something the landing page advertises. Also trigger when the user says "update the intro page", "regenerate the landing page", "refresh togomcp-intro.html", "the intro is out of date", or similar — even if they don't name the file. Spec for what the page should contain is this skill's `references/make_intro.md`; the rendered page is `togo_mcp/data/docs/togomcp-intro.html`.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

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

    The page is hand-edited HTML, not generated: Do not regenerate the entire file from scratch.

    line 12
  2. Distinctive:

    If a structural change crosses what the spec says (e.g.

    line 21
  3. Distinctive:

    When a section is out of date, do not re-derive it from memory.

    line 25
  4. Very specific:

    Read the new MIE file's schema_info.title and schema_info.description.

    line 47
  5. Very specific:

    Delete the corresponding <div class="db-card"> block.

    line 54
  6. Distinctive:

    If renamed, also update any other section that mentioned it (Summary card list, Examples that name it, etc.).

    line 55
  7. Very specific:

    Place the new <div class="tool-item">…</div> in the appropriate <div class="tool-group"> based on category:

    line 65
  8. Very specific:

    Delete the <div class="tool-item"> block.

    line 80
  9. Very specific:

    Run python scripts/generate_whatsnew.py and commit the updated HTML alongside the CHANGELOG.

    line 96
  10. Distinctive:

    Only the newest ~5 markers render.

    line 98
  11. Very specific:

    Numbers: when citing scale (e.g. "444M+ proteins"), prefer the figure from the MIE data_statistics over outside knowledge.

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

TogoMCP Intro Page Updater

The intro page (togo_mcp/data/docs/togomcp-intro.html) is the public landing page at https://togomcp.rdfportal.org/. It is a single self-contained HTML file with inline CSS and JS — there is no build step. Every section advertises some surface fact about the project; if that fact changes elsewhere in the repo, this page must be edited to match.

The hard rule

The page is hand-edited HTML, not generated. Do not regenerate the entire file from scratch. Edit only the section(s) affected by the change. The file is large (~1300 lines), so use Edit with surrounding context as the anchor.

Spec vs. rendered page

FileRole
references/make_intro.md (in this skill)Spec — what the page should contain, style requirements
togo_mcp/data/docs/togomcp-intro.htmlRendered page — the artifact users see

If a structural change crosses what the spec says (e.g. a new top-level section, a new menu tab), update both files. For routine catalog updates (a new database card, a renamed tool), only the HTML changes.

Sources of truth — what is canonical for each section

When a section is out of date, do not re-derive it from memory. Read the canonical source and reflect it in the HTML.

SectionCanonical source
Available Databasestogo_mcp/data/mie/*.yaml (one card per file, excluding supercon.yaml) + togo_mcp/data/resources/endpoints.csv
Available Tools@mcp.tool(...) decorators in togo_mcp/*.py (root server, plus togoid.py and ncbi_tools.py mounted as togoid_* and ncbi_*)
PreprintREADME.md (top-level) — citation block
Setup Guidemake_intro.md (Claude/ChatGPT/Gemini blocks) + the URLs for each platform's MCP docs
Other MCP Serversmake_intro.md recommended companion servers
Related Resourcesmake_intro.md (RDF Portal, TogoID, DBCLS) — verify URLs are alive
Source codehttps://github.com/dbcls/togomcp (DBCLS canonical repo)
Hero endpoint URLThe production MCP endpoint: https://togomcp.rdfportal.org/mcp
What's NewCurated user-facing highlights from CHANGELOG.md (released entries only) — see Scenario 6

Triggering edits — common scenarios

Scenario 1: New database added

A new database appears when there is a new togo_mcp/data/mie/<db>.yaml AND a new row in togo_mcp/data/resources/endpoints.csv. (One without the other is incomplete onboarding — flag it.)

To add the card:

  1. Read the new MIE file's schema_info.title and schema_info.description.
  2. Condense the description to one or two sentences (~150–250 chars), preserving concrete numbers (record counts, version, what's covered). Match the tone of existing cards — declarative, no marketing language.
  3. Insert a <div class="db-card">…</div> block in the #databases section. Pick the position by domain affinity with neighboring cards (proteins block, chemistry block, gene/genomics block, disease/clinical block, vocabulary/ontology block, taxonomy block, microbiology block, sequence block, etc.) — do not just append. The visual grouping matters because the grid auto-flows by source order.
  4. Skip supercon.yaml — it is intentionally excluded per the spec.

Scenario 2: Database removed or renamed

  1. Delete the corresponding <div class="db-card"> block.
  2. If renamed, also update any other section that mentioned it (Summary card list, Examples that name it, etc.).

Scenario 3: New tool added

Find the @mcp.tool decorator in togo_mcp/*.py. Tools are registered on three servers:

  • Root mcp (in rdf_portal.py, api_tools.py) — exposed as <tool_name>
  • togoid_mcp (in togoid.py) — exposed as togoid_<tool_name>
  • ncbi_mcp (in ncbi_tools.py) — exposed as ncbi_<tool_name>

Place the new <div class="tool-item">…</div> in the appropriate <div class="tool-group"> based on category:

Group headerBelongs in this group
📋 Database & InformationList/get tools for databases, endpoints, graphs, MIE
🔍 Keyword Search Toolssearch_* tools that hit a database's keyword-search API
⚡ SPARQL Queryrun_sparql and any new direct-query tools
🔄 ID Conversion (TogoID)togoid_* tools
🧬 NCBI E-utilitiesncbi_* tools
🧪 PubChem-specificPubChem-specific helpers

The tool-item-desc should be one short sentence — the user-facing purpose, not the function signature. Look at existing entries for tone.

Scenario 4: Tool removed or renamed

Delete the <div class="tool-item"> block. Also check Examples (the three example-card blocks) — they list tools used in <span class="tool-tag"> elements. If a removed/renamed tool appears there, update or replace it.

Scenario 5: Preprint, setup instructions, or external URLs change

For URLs in the Setup Guide, footer, or Related Resources: when changing, verify the URL is alive (e.g. with WebFetch or by checking the documented support article still exists). Dead links on the landing page are worse than missing entries.

Scenario 6: Keep "What's New" fresh (cross-cutting — GENERATED)

The #whats-new section (a .whatsnew-list of dated one-line entries, right after Summary) is generated, not hand-edited: its <li> items sit between <!-- WHATSNEW:START --> / <!-- WHATSNEW:END --> sentinels and are produced by scripts/generate_whatsnew.py from <!-- whatsnew: … --> markers in CHANGELOG.md. Do not edit the items directly — you'd be overwritten by the next generator run, and whatsnew.yml CI / tests/test_whatsnew_in_sync.py would flag the drift.

Whenever Scenario 1–5 fires — a database or tool is added / removed / renamed, or a user-visible capability changes — add a marker to CHANGELOG.md and regenerate:

  1. Under the relevant release heading (or [Unreleased] for non-release news), add: <!-- whatsnew: 2026-07-24 | one user-facing sentence -->
    • User-facing only (new DB, new/renamed/removed tool, format/capability change a user notices); skip internal refactors/tests.
    • Date is YYYY-MM or YYYY-MM-DD. Text is trusted inline HTML — plain, non-marketing tone; use <code> for tool names, <em>/<a> as needed; no literal -->.
  2. Run python scripts/generate_whatsnew.py and commit the updated HTML alongside the CHANGELOG.

Only the newest ~5 markers render. A stale What's New reads as abandonment — worse than none — so if you touch the page for any surface change and the top entry is old, add a marker for what just changed.

Style guide — conventions baked into the existing page

These are not strict rules but the patterns to match unless there's a reason to deviate:

  • Database card descriptions: 1–2 sentences, lead with what it is, follow with a concrete number or scope. No hyperbole. Examples to imitate: the existing UniProt, ChEMBL, Ensembl, PDB cards.
  • Tool item descriptions: ≤1 sentence, ≤120 chars, imperative ("Search …", "Get …", "Convert …"). No "This tool…" preamble.
  • Database card name: matches the canonical brand (UniProt, ChEMBL, BacDive — not all-caps, not lowercase). For ambiguous cases, use the form in the MIE schema_info.title. For very-uncommon abbreviations, expand in parentheses on first use (e.g. PDB (Protein Data Bank), OMA (Orthologous MAtrix) — but the existing page uses the bare abbreviation for OMA; match the local pattern).
  • Tool name: the actual tool name as registered on the MCP server (with the mount prefix where applicable: togoid_convertId, ncbi_esearch).
  • Numbers: when citing scale (e.g. "444M+ proteins"), prefer the figure from the MIE data_statistics over outside knowledge. If data_statistics is empty, omit the figure rather than invent one.
  • No emojis in card/item content — the section headers already use them.

Pre-finalisation checklist

  • Every togo_mcp/data/mie/<db>.yaml (except supercon.yaml) has a corresponding <div class="db-card"> and vice versa
  • Every @mcp.tool in togo_mcp/*.py has a corresponding <div class="tool-item"> and vice versa (with correct mount prefix)
  • Tool tags in the three Examples reference real, current tool names
  • Hero endpoint URL is https://togomcp.rdfportal.org/mcp
  • Preprint citation matches the top-level README.md
  • No reference to a deprecated tool (e.g. get_shex, get_sparql_example — both removed) anywhere on the page
  • Sticky nav <ul> items still match the actual <section id="…"> anchors
  • If this edit was a DB/tool/capability change, #whats-new has a fresh dated entry (Scenario 6) and the list is ~3–5 items, newest first

Common pitfalls

  • ❌ Regenerating the file end-to-end from make_intro.md. The spec is a guide, not a generator — running it through an LLM produces a different page each time and erases hand-tuning. Edit in place.
  • ❌ Adding a card by appending to the end of the grid. The grouping is intentional.
  • ❌ Including supercon.yaml in the database list — it is excluded by spec.
  • ❌ Inventing record counts or coverage figures. If you don't have a verified number, drop the figure.
  • ❌ Forgetting the mount prefix on togoid_* / ncbi_* tools.
  • ❌ Editing only the rendered HTML when a structural change should also update make_intro.md.

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.