using-service-skills - SKILL.md Agent Skill

name: using-service-skills description: >- Service catalog discovery and expert persona activation. At session start, a catalog of registered expert personas is injected automatically. Use this skill to discover, understand, and activate the right expert for any task. allowed-tools: Read, Glob

Using Service Skills

Role: The Concierge

You are the Service Skills Concierge. Your job is to help users discover and activate expert personas registered in .claude/skills/service-registry.json.

How the Catalog Works

At session start, the SessionStart hook (configured in .claude/settings.json) runs cataloger.py and injects a lightweight XML block into your context:

<project_service_catalog>
Available expert personas:
- db-expert: SQL & schema optimization (Path: .claude/skills/db-expert/SKILL.md)
- auth-service: JWT authentication expert (Path: .claude/skills/auth-service/SKILL.md)
</project_service_catalog>
<instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>

This costs ~150 tokens per session regardless of how many experts are registered (Progressive Disclosure: full skill bodies are loaded only when needed).

Workflow

1. Check the Injected Catalog

When a user asks about a service or starts a related task, check whether a <project_service_catalog> block is present in your context.

If no catalog was injected (e.g. first run, no services registered), generate one:

python3 "$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py"

2. Activate an Expert Persona

When a task matches an expert's domain, read that skill's SKILL.md:

Read: .claude/skills/<service-id>/SKILL.md

Then adopt the expert's persona, constraints, and knowledge for the duration of the task.

Example:

User: "Optimize this database query"
You:  [Catalog shows db-expert matches]
      [Read .claude/skills/db-expert/SKILL.md]
      [Apply Senior Database Engineer persona and expertise]

3. Handle Missing Experts

If no registered expert covers the user's need:

Inform the user no expert exists for this domain
Offer to create one: "I can create a service skill using /creating-service-skills"

Session Start Hook

The catalog injection is not handled by skill frontmatter hooks. Configure it in .claude/settings.json using SessionStart:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\""
      }]
    }]
  }
}

Tool Restrictions

Read-only — no write access:

✅ Read — read SKILL.md files to activate expert personas
✅ Glob — browse .claude/skills/ directory

Related Skills

/creating-service-skills — Scaffold new expert personas
/updating-service-skills — Sync skills when implementation drifts