jaggerxtrm/service-skills

Service Skills

The single entry point for a project's service-skills system. Each service gets a dedicated expert package — architecture, data flows, failure modes, runnable health checks, deploy/runbook, and diagnostic scripts — that agents load on demand instead of re-deriving the service every session. This router tells you which flow to run and points at the detailed reference for each.

Two skills share the service-skills name by design, at different layers:

• This machinery skill (service-skills) — the create/use/update/scope tooling. Shipped once.
• The per-repo umbrella (<repo>-services) — one generated skill per repo that maps that repo's services and links their per-service skills. Repo-qualified name avoids collision.

---

Pick the Flow

| You want to… | Flow | Reference | Trigger | |---|---|---|---| | Stand up a new service skill (scaffold + deep dive) | create | references/creating.md | /creating-service-skills | | Find & activate the right expert for a task | use | references/using.md | /using-service-skills (auto at session start) | | Sync a skill after the code changed (drift) | update | references/updating.md | /updating-service-skills (auto on Write/Edit) | | Scope a task to the right service(s) before touching files | scope | references/routing.md | /scope "task" |

Supporting references: system-guide.md (how the whole system fits together), script_quality_standards.md (diagnostic-script templates), and the canonical section contract references/service_skill_contract.json (SSOT for SKILL.md headings, order, and the <!-- SEMANTIC_START/END --> protected region).

---

Scope First (absorbed routing)

Before any investigation, feature, refactor, config-change, or exploration task that involves a service, ground it in the right expert context before touching files. Read the registry, detect intent, map to service(s), emit a scope plan, load the skills, then act.

Detect intent from the task description:

| Intent | Signal keywords | |---|---| | investigation | broken, error, failing, not working, crash, down, missing, slow, 502, 404, 429, timeout | | feature | add, implement, create, new, build, support | | refactor | refactor, restructure, clean, reorganize, rename, extract | | config-change | update, change, modify, set, configure, tune | | exploration | how, explain, understand, what is, why, walk me through |

Default when ambiguous → investigation (check first, act second). Map symptoms to services, confirm ownership with the graph when a task names a symbol rather than a path, then run the full scope flow in references/routing.md (intent workflows, XML scope block, regression-test binding).

python3 "$CLAUDE_PROJECT_DIR/.claude/skills/service-skills/scripts/scope.py"   # registry + routing footer

---

Navigate With the Graph, Not Just Globs

The registry maps a service to its territory globs — enough to find the skill, not to understand cross-service reach. Once an expert is active, navigate with the GitNexus graph:

| Question | Use | |---|---| | "What else breaks if I change this symbol?" | gitnexus impact <symbol> --direction upstream | | "Who calls / is called by this?" | gitnexus context <symbol> | | "Which service owns this execution flow?" | gitnexus query "<concept>" | | "Trace the full flow end to end" | READ gitnexus://repo/<repo>/process/<name> |

Fallback: with no GitNexus index, route by registry globs + cross_territory hints in drift output. The graph is an enhancement, never a hard dependency.

---

Drift Cadence (update flow)

The automatic sync pipeline runs post-merge on master only (not on feature-branch merges) — the single point where code is final. Drift is measured semantically since each service's last_sync_ref (committed range last_sync_ref..HEAD), not by file mtime alone, and tiered cosmetic | medium | high | unknown with explicit provenance. See references/updating.md.

python3 "$CLAUDE_PROJECT_DIR/.claude/skills/service-skills/scripts/drift_detector.py" scan

---

Scripts

All machinery scripts live together under scripts/ (no cross-skill imports):

| Script | Role | |---|---| | bootstrap.py | Path/registry resolvers (get_project_root, get_pack_path, get_registry_path), gitnexus helpers | | scaffolder.py | Phase-1 skeleton from compose/Dockerfile/deps | | deep_dive.py | Service-type classification + Phase-2 research agenda | | drift_detector.py | GitNexus-aware drift scan / sync / check-hook | | skill_migrator.py | Upgrade a pre-devops SKILL.md to the current section contract (idempotent, SEMANTIC-preserving) | | cataloger.py | Session-start service catalog injection | | skill_activator.py | PreToolUse territory → load-skill enforcement | | scope.py | Registry read + routing footer for the scope flow |

Install machinery (hooks + settings + git-hooks) lives under install/; see install/service-skills-readme.md.

umbrella_generator.py renders the per-repo umbrella (below).

---

Per-Repo Umbrella (generated)

Each repo gets one umbrella skill — name: <repo>-services — at .xtrm/skills/user/packs/<pack>/service-skills/SKILL.md. It is generated from service-registry.json (service table + cross-service health + navigation) so it can never drift from the registered services. The human cross-service narrative lives in a <!-- SEMANTIC_START --> / <!-- SEMANTIC_END --> block preserved verbatim across regeneration — edit only there.

python3 scripts/umbrella_generator.py <repo-name>   # regenerate (idempotent)

install-service-skills.py regenerates the umbrella on install/upgrade. Load the umbrella first when a task spans services; it links each per-service skill.

---

Installation

cd ~/projects/my-project
python3 /path/to/xtrm-tools/skills/service-skills/install/install-service-skills.py

Idempotent — wires settings.json hooks (SessionStart catalog · PreToolUse activator · PostToolUse drift), activates git hooks, and migrates already-installed skills to the current section contract. Safe to re-run after upgrades.