t1k:find-skill

Field	Value
Module	`t1k-base`
Version	`3.6.6`
Effort	`low`
Tools	—

Keywords: agents, available, capabilities, discover, find, list, lookup, search, skills

How to invoke

/t1k:find-skill
<query> [--all] [--installed-only]

TheOneKit Find-Skill — Capability Discovery (Skills & Agents)

Search available skills AND agents when you need to know what capability exists. Critical as module and agent count grows across kits.

Usage

/t1k:find-skill "ECS batch processing"   # Find skills matching a query
/t1k:find-skill "auth"                   # All skills related to auth
/t1k:find-skill --all                    # List every available skill
/t1k:find-skill --all --installed-only   # Only installed skills

Algorithm

Load activation sources:
- Read ALL .claude/t1k-activation-*.json fragments → collect keyword-to-skill mappings
- Read ALL .claude/t1k-routing-*.json fragments → collect role→agent mappings
- Read ALL installed module.json files → collect activation.keywords per module
- Read ALL SKILL.md frontmatter (description field) for richer matching
- Read .claude/agents/ (Glob BOTH .claude/agents/*.md AND .claude/agents/**/*.md) → collect agent names + description frontmatter (kits may nest agents under subdirectories — a flat-only glob returns zero agents there)
Scan caps the first 30 lines per file (frontmatter only) and limits results to 50 matches by default; use --all to bypass.
Fuzzy-match query:
- Tokenize user query into words
- Match against: activation keywords, skill names, agent names/roles, routing roles, SKILL.md + agent descriptions
- Rank results:
  1. Exact keyword match (highest)
  2. Prefix match (query is prefix of keyword)
  3. Substring match (query appears inside keyword)
  4. Description match (query word appears in SKILL.md description)
Resolve install status:
- Read .claude/metadata.json → installedModules
- Mark each result: [installed] or [not installed — module: {name}]
Output results with install status, module, and description.

Output Format

## Skills matching "ECS batch"

### Installed

| Skill | Module | Description |
|-------|--------|-------------|
| dots-ecs-core | dots-core (theonekit-unity) | ECS system patterns, burst compilation, job scheduling |
| dots-ecs-batch | dots-core (theonekit-unity) | Batch entity processing with IJobChunk and EntityQuery |

### Available (not installed)

| Skill | Module | Kit | Install Command |
|-------|--------|-----|-----------------|
| dots-ecs-advanced | dots-advanced | theonekit-unity | /t1k:modules add dots-advanced |

### No match in uninstalled modules.

Agents Matching (agent queries)

When the query is agent-shaped (which agent, agent for, list agents, …), ALSO report the matching agent roster:

## Agents matching "kit"

### Installed
| Agent | Role | Description |
|-------|------|-------------|
| t1k-kit-developer | kit-developer | Kit infrastructure, release, registry, CI/CD |

### From routing tables
| Role | Agent |
|------|-------|
| implementer | t1k-fullstack-developer |

Agent sources: t1k-routing-*.json role tables (canonical role→agent mapping per layer), plus .claude/agents/** frontmatter (name, description) for roster/ capability detail. Distinguish a t1k-agents question (renders the LIVE session spawn tree) from capability discovery — this skill answers the latter.

—all Flag

Lists every available skill AND agent (no filtering). Output grouped by module (skills) and by routing layer (agents):

## All Available Skills

### Core (always available)
- t1k:cook — End-to-end feature implementation
- t1k:fix — Bug fix workflow
- t1k:plan — Planning and architecture
- ...

### Module: dots-core (theonekit-unity) [installed v2.1.0]
- dots-ecs-core — ECS system patterns
- dots-physics — Physics simulation patterns
- ...

### Module: ui (theonekit-unity) [installed v1.3.0]
- unity-ui — UI toolkit patterns
- ...

### Module: rendering (theonekit-unity) [NOT INSTALLED]
  Install: /t1k:modules add rendering
- unity-rendering — SRP render pipeline patterns
- ...

Uninstalled Module Suggestion

When results include uninstalled modules, offer installation:

2 results found in uninstalled module 'dots-advanced'.
Install it? Run: /t1k:modules add dots-advanced

Do NOT auto-install — always ask the user first.

Category Browsing

When no query provided (or --all), group skills by category (from module.json → category):

/t1k:find-skill --all --category "Testing & QA"

Available categories: Core Workflows, Planning & Analysis, Backend, Frontend & Design, Game Engine, Testing & QA, DevOps & CI/CD, Security, Documentation, Git & VCS, Kit Management, Utilities

Gotchas

Core skills are always available — they live in .claude/skills/ regardless of metadata
Fragment-only kits: Some older kits may not have module.json — fall back to t1k-activation-*.json only
Description quality varies: SKILL.md descriptions may be short; keyword matching is more reliable
Cross-kit skills: A skill installed from theonekit-designer appears in results even in a Unity project
Agent layout is kit-dependent: some kits keep flat .claude/agents/*.md; others nest under subdirectories. Glob BOTH patterns — a flat-only glob reports zero agents in a nested-only kit (e.g. theonekit-unity)
Activation refs accept BOTH bare and full-prefixed forms — when resolving a mappings[].skills[] entry from a fragment to its skill dir, accept either nakama-rpc (bare slug) or t1k-nakama-rpc (full-prefixed dir name). The CI prefixer self-heals legacy bare refs to canonical form at release time, but the SSOT in fragment files stays bare. If a ref doesn’t resolve via either form, it’s drift — surface to the user (consult t1k-doctor check #47 or release-action validate-activation-skill-resolution.cjs).

Auto-Activation Keywords

Triggers on: find skill, search skill, what skill, available skills, discover, how do I, which skill, skill for, list skills, skill search, which agent, what agent, find agent, list agents, list agent, agent for, do we have an agent, is there an agent, available agents, agent discovery