add-service
Skill3 starsChanged 4 months agoMITView on GitHub
Add a service capsule (or Kafka topic node) to the Cosmos map. Use when the user says "add service X to the cosmos", "wire X into the map", or "add a topic node for Y". Researches the service from source, maps all its connections, then adds SERVICES/TOPICS entries to src/scenarios/ with correct position, color, and tech tags. Does not add scenario steps — that's add-scenario.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- TryGhost/Ghosttheir own version, first seen Nov 15, 2026
- lbedner/aegis-stacktheir own version, first seen Oct 8, 2026
- jblemee/docker-compose-homelabtheir own version, first seen Sep 3, 2026
- ficaviolaodorata520/met-museum-mcp-servertheir own version, first seen Jun 1, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- TryGhost/Ghost★ 56ksame name
- lbedner/aegis-stack★ 146same name
- jblemee/docker-compose-homelab★ 9same name
- ficaviolaodorata520/met-museum-mcp-server★ 0same 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 repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-scenarioSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 6 are distinctive, and 8 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use this skill when the user says "add X to the cosmos", "wire service X into the map", or "add a topic node for Y".
- Distinctive: line 28
Before touching any file, grep and read the service's source code (use an Explore agent for repos not in the workspace).
- Distinctive: line 39
Only proceed once you can answer all of these from source — never guess.
- Very specific: line 45
Before writing any entry, build a connection table.
- Distinctive: line 59
After filling the table, for each ❌:
- Distinctive: line 72
Check it doesn't already exist first:
- Distinctive: line 78
If it exists — stop, inform the user, and suggest updating the existing entry instead.
- Very specific: line 116
Read existing x/y positions before placing.
- Distinctive: line 119
If the user gives you coordinates, use them directly.
- Very specific: line 125
If you need a truly new hue, add it to every theme block in tokens.css.
- Very specific: line 130
Add it to the Tech union in types.ts
- Very specific: line 131
Add a { label, color, monogram } entry to TECH_META in src/components/TechIcon.tsx
- Very specific: line 137
If you add a new expandable ecosystem, also extend legsForStep() in src/map/edge-resolver.ts and the internal-edges block in …
- Very specific: line 141
If the new service is a standalone browser-facing UI, add its id to UI_SERVICE_IDS in src/map/UICluster.tsx.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add a service (or topic) to the Cosmos
Use this skill when the user says "add X to the cosmos", "wire service X into the map", or "add a topic node for Y". This covers adding a standalone capsule — it does not add scenario steps (use the add-scenario skill for that).
What you'll touch
| File | Why |
src/scenarios/services.ts | Add entries to SERVICES |
src/scenarios/topics.ts | Add entries to TOPICS (only for topics used in scenario steps) |
src/scenarios/owners.ts | Team ownership mapping |
src/scenarios/types.ts | Only if you need a new Tech variant |
src/components/TechIcon.tsx | Only if you added a new Tech variant |
src/styles/tokens.css | Only if you need a new --svc-* color hue |
src/map/UICluster.tsx | Only if the new service is a browser-facing UI surface |
Step 1 — Research the service
Before touching any file, grep and read the service's source code (use an Explore agent for repos not in the workspace). You need:
- What does this service do? (one sentence role)
- What stack does it run on? (framework, language)
- What databases / infra does it use? (Kafka, Redis, Postgres, object storage…)
- What Kafka topics does it produce / consume?
- What HTTP endpoints does it expose or call?
- What other services call it? What does it call?
- What WebSocket connections does it open or accept?
- What is its repository name in your GitHub org?
Only proceed once you can answer all of these from source — never guess.
Step 2 — Map all connections
Before writing any entry, build a connection table. This is the most important step — it determines what goes into desc, what Kafka topics to add, which existing service descriptions to update, and what to flag as missing.
For every connection the new service has, fill in this table:
| Direction | Protocol | Counterpart | Counterpart in cosmos? | Topic in cosmos? |
| → outbound | HTTP | payments | ✅ payments | n/a |
| ← inbound | Kafka (consume) | orders | ✅ orders | orders.created ❌ missing |
Rules:
- Counterpart in cosmos? —
grep -n "id: 'svc-id'" src/scenarios/services.tsfor each one - Topic in cosmos? —
grep -n "id: 'topic-name'" src/scenarios/topics.tsfor Kafka hops - For anything ❌: either add it now (if it's a known service) or flag it in the Connection summary below
After filling the table, for each ❌:
- Missing service → add it using this skill, OR note it as "not yet in cosmos" in
desc - Missing topic → add a
TOPICSentry if it will be used in a scenario stepvia:; otherwise just document it in thedescof both producer and consumer - Existing service whose
descis now stale → update itsdescto mention the new connection
Step 3 — Decide what to add
- Service = a deployed process (backend service, browser app, binary). Gets a capsule.
- Topic = a Kafka topic used as an intermediary between two services. Gets a small orbital node. Add a topic entry only if it is referenced via the
via:field in an existing or planned scenario step.
Check it doesn't already exist first:
grep -n "id: 'your-service-id'" src/scenarios/services.ts src/scenarios/topics.tsIf it exists — stop, inform the user, and suggest updating the existing entry instead.
Step 4 — Add the Service entry
Append to the SERVICES array in src/scenarios/services.ts, near logically related services:
{
id: 'my-service', // kebab-case repo name — must be unique
x: 1300, y: 600, // see positioning rules below
width: 230, height: 66, // 200–250 width; height always 66
color: 'var(--svc-blue)', // CSS token from tokens.css
hex: '#4f8ff7', // MUST match the token's hue — used in SVG gradients
name: 'my-service',
sub: 'NestJS · Postgres', // short stack line
code: 'MYS-19', // arbitrary display code
lang: 'TypeScript',
role: 'One-line role label',
desc: `Full description. Cover: what it owns, what triggers it,
what it produces, AND which other services it connects to (with protocol).
Call out any connections to services not yet in the cosmos explicitly.
2–5 sentences.`,
tech: ['typescript', 'nestjs', 'postgres', 'kafka'],
repo: 'my-service', // repo name in your org; omit for non-repo nodes (object storage etc.)
},The desc field must include all connections. Pattern:
- "Receives checkout requests from
api-gatewayover HTTP" - "Produces
orders.created(consumed byshipping,inventory)" - "Pushes live updates to
storefrontviarealtime-hub"
Positioning rules
The world is 2400 × 1400.
- Read existing
x/ypositions before placing. Don't overlap (capsules arewidth × 66; keep ≥150px center-to-center). - Group with logically related services — look at where the service's main callers/callees sit and join that neighborhood.
- Browser-facing UI surfaces live in the left band by convention.
- If the user gives you coordinates, use them directly.
Colors
Pick the --svc-* token (see src/styles/tokens.css) that is least used nearby OR best matches the service's family. hex must visually match the token's hue — it's used in SVG gradients where CSS vars don't work. Topics always use TOPIC_COLOR / TOPIC_HEX (orange) — never change that.
If you need a truly new hue, add it to every theme block in tokens.css.
Tech tags
Valid values are the Tech union in src/scenarios/types.ts. If you need a new tech tag:
- Add it to the
Techunion intypes.ts - Add a
{ label, color, monogram }entry toTECH_METAinsrc/components/TechIcon.tsx
Service ecosystems (sub-services)
If the service is an umbrella over several deployed processes (like the demo's realtime-hub = ingest + router + presence + push), use subServices: SubService[] instead of adding N separate capsules. The parent capsule renders a + expand button and explodes into a mini solar system. Slot order matters: slot 0 (NE) = intake, slot 3 (NW) = output.
If you add a new expandable ecosystem, also extend legsForStep() in src/map/edge-resolver.ts and the internal-edges block in src/map/Map.tsx (both currently handle realtime-hub).
UI cluster
If the new service is a standalone browser-facing UI, add its id to UI_SERVICE_IDS in src/map/UICluster.tsx. Don't add embedded overlays or in-app views — standalone web surfaces only.
Step 5 — Add Topic entries (if needed)
{
id: 'my-service.event-name', // exact Kafka topic name
x: 1450, y: 820, // between producer and consumer
name: 'my-service.event-name',
color: TOPIC_COLOR, hex: TOPIC_HEX,
desc: `Producer: X. Consumer: Y. What it carries and when it fires.`,
},Step 6 — Update affected service descriptions
Go back to the connection table from Step 2. For every ✅ counterpart whose desc doesn't already mention the new service, update it so the relationship is visible from both sides.
Step 7 — Connection summary (always output this)
### Connections wired into cosmos
- my-service ←HTTP— api-gateway (api-gateway.desc updated)
- my-service —Kafka→ orders (orders.created topic added)
### Connections NOT yet in cosmos
- my-service —HTTP→ legacy-billing (service not in cosmos — noted in desc)Step 8 — Verify
npx tsc -b --noEmit # must pass
npm run build # must passHard rules:
- ❌ Never run
tscwithout--noEmit/-b— stray.jsfiles shadow.tsxin Vite and silently break the app. - ❌ Never duplicate an
id— ids must be unique across bothSERVICESandTOPICS. - ❌ Never place a service that overlaps an existing node.
- ❌ Never invent a
hexthat doesn't match the CSS-var hue.
Quick checklist
- Researched from source (not guessed)
- Connection table filled — every counterpart checked
idunique — confirmed with grep- Position doesn't overlap
color/hexconsistent- All
techvalues exist in theTechunion - Team added/updated in
owners.ts - Topic nodes added for topics used in
via:steps - Counterpart
descfields updated - Connection summary printed
npx tsc -b --noEmitandnpm run buildpass
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
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.

