synaptiai/capability-discovery

Capability Discovery

This skill discovers available capabilities (skills, agents, commands) in the user's environment to enable dynamic workflow adaptation.

Purpose

Before executing workflows, discover what tools are available so commands can:

• Invoke specialized agents if available
• Use custom skills instead of defaults
• Apply project-specific quality commands
• Gracefully fall back when capabilities are missing

Discovery Process

<!-- PARALLEL EXECUTION: Steps 1-5 are fully independent. Execute ALL five simultaneously in a single message with parallel tool calls. Step 6 is conditional — only execute if Steps 4-5 detected a tech stack or quality commands (see Early Exit section). -->

Step 1: Scan for Custom Agents

Find agent files and extract their description from YAML frontmatter.

1a. Use Glob (two parallel calls) to find agent files:

• Glob: pattern=".claude/agents/*.md" — project-level agents
• Glob: pattern="plugins/*/agents/*.md" — plugin agents

1b. Use Grep on discovered files to extract descriptions:

• Grep: pattern="^description:" path="{file}" output_mode="content"

Parse each result:

• Source: project (from .claude/agents/) or plugin name (from plugins/{name}/agents/)
• Agent name: filename without .md extension
• Description: text after description: on the matched line

If no files found by Glob, report "No custom agents found" and continue.

Step 2: Scan for Custom Skills

Find skill files and extract their description from SKILL.md frontmatter.

2a. Use Glob (two parallel calls) to find skill files:

• Glob: pattern=".claude/skills/*/SKILL.md" — project-level skills
• Glob: pattern="plugins/*/skills/*/SKILL.md" — plugin skills

2b. Use Grep on discovered files to extract descriptions:

• Grep: pattern="^description:" path="{file}" output_mode="content"

Parse each result:

• Source: project (from .claude/skills/) or plugin name (from plugins/{name}/skills/)
• Skill name: parent directory of the SKILL.md file
• Description: text after description: on the matched line

If no files found by Glob, report "No custom skills found" and continue.

Step 3: Scan for Custom Commands

Find command files and extract their description from YAML frontmatter.

3a. Use Glob (two parallel calls) to find command files:

• Glob: pattern=".claude/commands/*.md" — project-level commands
• Glob: pattern="plugins/*/commands/*.md" — plugin commands

3b. Use Grep on discovered files to extract descriptions:

• Grep: pattern="^description:" path="{file}" output_mode="content"

Parse each result:

• Source: project (from .claude/commands/) or plugin name (from plugins/{name}/commands/)
• Command name: filename without .md extension
• Description: text after description: on the matched line

If no files found by Glob, report "No custom commands found" and continue.

Step 4: Parse CLAUDE.md for Quality Commands

Check both .claude/CLAUDE.md and root CLAUDE.md (prefer .claude/CLAUDE.md):

# Determine CLAUDE.md path
CLAUDE_MD=""
[ -f ".claude/CLAUDE.md" ] && CLAUDE_MD=".claude/CLAUDE.md"
[ -z "$CLAUDE_MD" ] && [ -f "CLAUDE.md" ] && CLAUDE_MD="CLAUDE.md"

if [ -n "$CLAUDE_MD" ]; then
  echo "Found: $CLAUDE_MD"

  # Explicit quality command definitions (key: value format)
  grep -E "^(lint|test|check|format|typecheck|build):" "$CLAUDE_MD" 2>/dev/null

  # npm/pnpm/yarn/bun script references
  grep -E "(npm|pnpm|yarn|bun) (run )?(lint|test|check|format|build|typecheck)" "$CLAUDE_MD" 2>/dev/null

  # Python tool references
  grep -E "(ruff|pytest|poetry run|python -m pytest|mypy|pyright|black|isort|flake8|pylint)" "$CLAUDE_MD" 2>/dev/null

  # Go tool references
  grep -E "(go vet|go test|golangci-lint)" "$CLAUDE_MD" 2>/dev/null

  # Rust tool references
  grep -E "(cargo (clippy|test|fmt|check))" "$CLAUDE_MD" 2>/dev/null

  # Make targets
  grep -E "^(lint|test|check|format):" "$CLAUDE_MD" 2>/dev/null
  grep -E "make (lint|test|check|format)" "$CLAUDE_MD" 2>/dev/null
else
  echo "No CLAUDE.md found"
fi

Step 5: Detect Tech Stack and Extract Config

# Detect stack and extract actionable config
[ -f "pyproject.toml" ] && echo "python" && grep -A5 '\[tool.ruff\]\|\[tool.pytest\]\|\[tool.mypy\]' pyproject.toml 2>/dev/null | head -20
[ -f "package.json" ] && echo "node" && python3 -c "import json; d=json.load(open('package.json')); [print(f'  script: {k} = {v}') for k,v in d.get('scripts',{}).items() if any(w in k for w in ['lint','test','check','build','dev','start','format','typecheck','e2e'])]" 2>/dev/null
[ -f "tsconfig.json" ] && echo "typescript"
[ -f "go.mod" ] && echo "go"
[ -f "Cargo.toml" ] && echo "rust"
[ -f "Gemfile" ] && echo "ruby"
[ -f "Makefile" ] && echo "makefile" && grep -E '^(lint|test|check|format|build|dev|serve):' Makefile 2>/dev/null

Early Exit: Markdown-Only Projects

If Step 5 detected no tech stack files (none of pyproject.toml, package.json, tsconfig.json, go.mod, Cargo.toml, Gemfile, Makefile) and Step 4 found no quality commands in CLAUDE.md:

Skip Step 6 and produce the output with:

• Quality Commands: "No code-related quality commands applicable"
• Tech Stack: "Markdown-only project (no code runtime detected)"
• Verification Capabilities: "N/A for markdown-only project"
• Recommended Workflow: Focus on agent/skill dispatch only, omit quality command recommendations

Step 6: Discover Verification Capabilities

# Determine CLAUDE.md path
CLAUDE_MD=""
[ -f ".claude/CLAUDE.md" ] && CLAUDE_MD=".claude/CLAUDE.md"
[ -z "$CLAUDE_MD" ] && [ -f "CLAUDE.md" ] && CLAUDE_MD="CLAUDE.md"

# Check for runtime verification commands in CLAUDE.md
[ -n "$CLAUDE_MD" ] && grep -E "^(dev-server|verify|e2e|smoke|health):" "$CLAUDE_MD" 2>/dev/null

# Check for verification scripts
ls verify.sh scripts/verify* test-e2e.sh smoke-test.sh 2>/dev/null

# Check for E2E frameworks
ls playwright.config.* cypress.config.* 2>/dev/null
grep -l "playwright\|cypress\|selenium" package.json pyproject.toml 2>/dev/null

# Check for dev server in package.json scripts (proper JSON extraction)
python3 -c "import json; d=json.load(open('package.json')); [print(f'{k}: {v}') for k,v in d.get('scripts',{}).items() if k in ('dev','start','serve')]" 2>/dev/null

Output Format

Report discovered capabilities in structured format. The calling command uses this output to decide which agents to dispatch, which quality commands to run, and how to adapt the workflow.

## Discovered Capabilities

### Agents Available
| Agent | Source | Description |
|-------|--------|-------------|
| code-reviewer | gh-workflow | Code quality analysis |
| convention-checker | gh-workflow | Git convention validation |
| test-runner | gh-workflow | Quality command execution |
| implementation-planner | gh-workflow | Task breakdown from acceptance criteria |
| custom-agent | project | [extracted from frontmatter] |

### Skills Available
| Skill | Source | Description |
|-------|--------|-------------|
| repo-config | gh-workflow | Dynamic repo configuration |
| runtime-verification | gh-workflow | Runtime smoke/E2E testing |
| suggest-users | gh-workflow | Reviewer/assignee suggestion |
| custom-skill | project | [extracted from frontmatter] |

### Quality Commands
| Command | Purpose | Source |
|---------|---------|--------|
| `ruff check .` | Python linting | CLAUDE.md |
| `pytest` | Python tests | CLAUDE.md |
| `npm run lint` | JavaScript linting | package.json scripts |

### Tech Stack Detected
- Python (pyproject.toml found)
- TypeScript (tsconfig.json found)

### Verification Capabilities
| Capability | Command | Source |
|-----------|---------|--------|
| Dev server | `npm run dev` | package.json scripts.dev |
| E2E tests | `npx playwright test` | playwright.config.ts detected |
| Health check | `curl localhost:3000/health` | CLAUDE.md |

### Recommended Workflow
Based on capabilities:
1. Use `code-reviewer` agent for code analysis
2. Use `convention-checker` for Git validation
3. Run `ruff check .` then `pytest` for quality
4. Invoke `lint` skill if project-specific

Usage in Commands

In gh-start (Phase 3)

Before implementation:
1. Invoke capability-discovery skill
2. Note available agents for later review phases
3. Note quality commands for Phase 6
4. Store tech stack for appropriate tooling

In gh-pr (Phase 1 Step 1.2)

Before PR creation:
1. Invoke capability-discovery skill
2. Extract LINT_CMD, TEST_CMD, TYPECHECK_CMD for Phase 3
3. Note available agents for review dispatch

In gh-review (Phase 2)

Before detailed review:
1. Check for review-specific agents (code-reviewer, convention-checker)
2. Check for quality skills (lint, test)
3. Plan review facets based on available capabilities

In gh-address (Phase 2)

Before addressing feedback:
1. Invoke capability-discovery skill
2. Extract quality commands for Phase 5 verification
3. Note available agents for Phase 6 code review

In gh-resolve (Step 2.2)

Before post-resolution verification:
1. Invoke capability-discovery skill
2. Extract LINT_CMD, TEST_CMD, TYPECHECK_CMD for Phase 5
3. If skill fails, fall back to tech-stack detection table

Graceful Degradation

When capabilities are not found:

| Missing Capability | Fallback | |-------------------|----------| | No custom agents | Use built-in review checklist | | No lint skill | Detect from tech stack | | No CLAUDE.md commands | Use standard tools for detected stack | | No tech stack detected | Ask user for commands | | No package.json scripts | Fall back to grep-based detection |

Integration Points

This skill is invoked by:

• gh-start — Phase 3 (before implementation)
• gh-pr — Phase 1 Step 1.2 (before PR creation)
• gh-review — Phase 2 (before code review)
• gh-address — Phase 2 (before addressing feedback)
• gh-resolve — Step 2c (quality command discovery for post-resolution verification)

Results inform:

• Which agents to delegate to (code-reviewer, convention-checker, test-runner, implementation-planner)
• Which quality commands to run (LINT_CMD, TEST_CMD, TYPECHECK_CMD)
• How to adapt workflow to project capabilities

Caching note: This skill runs in a forked context. The calling command must store the returned output (agent list, quality commands, tech stack) in its own context for use in later phases. Do not re-invoke this skill within the same command execution.

Best Practices

1. Prefer explicit — CLAUDE.md commands take precedence over tech-stack inference
2. Report clearly — Show what was found and what wasn't so the caller can plan fallbacks
3. Enable fallbacks — Never block workflow due to missing capabilities
4. Extract descriptions — Agent/skill descriptions help the caller decide what to dispatch