capability-discovery · diff
git:20260305.d5d457e to git:20260305.cc4effe
133 added, 62 removed. Audit A to A.
---
name: capability-discovery
- description: >-
- WHEN: Before starting implementation (gh-start Phase 3), before reviewing a PR (gh-review Phase 2),
- or before addressing feedback (gh-address). Use to discover available agents, skills, quality commands,
- and tech stack in the project environment.
- WHEN NOT: Do not use mid-implementation or for runtime verification -- use runtime-verification skill instead.
+ description: Discovers available agents, skills, quality commands (lint, test, typecheck), and tech stack in the project environment. Use when starting implementation, creating PRs, reviewing PRs, or addressing feedback to determine which agents to dispatch and which quality commands to run. Use before workflow execution to adapt gh-workflow commands to project-specific tooling.
allowed-tools: Bash, Read, Glob, Grep
context: fork
agent: Explore
---
# 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-6 are fully independent. Execute ALL steps
+ simultaneously in a single message with parallel tool calls.
+ -->
+
### Step 1: Scan for Custom Agents
+ List agent files and extract their `description` from YAML frontmatter:
+
```bash
# Project-level agents
- ls .claude/agents/*.md 2>/dev/null | xargs -I {} basename {} .md
+ for f in .claude/agents/*.md; do
+ [ -f "$f" ] || continue
+ agent=$(basename "$f" .md)
+ desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$f")
+ echo "project:$agent|$desc"
+ done
# Plugin agents
- ls plugins/*/agents/*.md 2>/dev/null | while read f; do
- plugin=$(echo $f | cut -d'/' -f2)
- agent=$(basename $f .md)
- echo "$plugin:$agent"
+ for f in plugins/*/agents/*.md; do
+ [ -f "$f" ] || continue
+ plugin=$(echo "$f" | cut -d'/' -f2)
+ agent=$(basename "$f" .md)
+ desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$f")
+ echo "$plugin:$agent|$desc"
done
```
### Step 2: Scan for Custom Skills
+ List skill directories and extract their `description` from SKILL.md frontmatter:
+
```bash
# Project-level skills
- ls .claude/skills/*/SKILL.md 2>/dev/null | while read f; do
- skill=$(dirname $f | xargs basename)
- echo "$skill"
+ for f in .claude/skills/*/SKILL.md; do
+ [ -f "$f" ] || continue
+ skill=$(basename "$(dirname "$f")")
+ desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$f")
+ echo "project:$skill|$desc"
done
# Plugin skills
- ls plugins/*/skills/*/SKILL.md 2>/dev/null | while read f; do
- plugin=$(echo $f | cut -d'/' -f2)
- skill=$(dirname $f | xargs basename)
- echo "$plugin:$skill"
+ for f in plugins/*/skills/*/SKILL.md; do
+ [ -f "$f" ] || continue
+ plugin=$(echo "$f" | cut -d'/' -f2)
+ skill=$(basename "$(dirname "$f")")
+ desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$f")
+ echo "$plugin:$skill|$desc"
done
```
### Step 3: Scan for Custom Commands
+ List command files and extract their `description` from YAML frontmatter:
+
```bash
# Project-level commands
- ls .claude/commands/*.md 2>/dev/null | xargs -I {} basename {} .md
+ for f in .claude/commands/*.md; do
+ [ -f "$f" ] || continue
+ cmd=$(basename "$f" .md)
+ desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$f")
+ echo "project:$cmd|$desc"
+ done
# Plugin commands
- ls plugins/*/commands/*.md 2>/dev/null | while read f; do
- plugin=$(echo $f | cut -d'/' -f2)
- cmd=$(basename $f .md)
- echo "$plugin:$cmd"
+ for f in plugins/*/commands/*.md; do
+ [ -f "$f" ] || continue
+ plugin=$(echo "$f" | cut -d'/' -f2)
+ cmd=$(basename "$f" .md)
+ desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$f")
+ echo "$plugin:$cmd|$desc"
done
```
### Step 4: Parse CLAUDE.md for Quality Commands
+ Check both `.claude/CLAUDE.md` and root `CLAUDE.md` (prefer `.claude/CLAUDE.md`):
+
```bash
- # Look for explicit quality command definitions
- grep -E "^(lint|test|check|format|typecheck|build):" .claude/CLAUDE.md 2>/dev/null
+ # 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"
- # Look for npm scripts references
- grep -E "npm run (lint|test|check|format|build)" .claude/CLAUDE.md 2>/dev/null
+ if [ -n "$CLAUDE_MD" ]; then
+ echo "Found: $CLAUDE_MD"
- # Look for Python tool references
- grep -E "(ruff|pytest|mypy|pyright|black|isort)" .claude/CLAUDE.md 2>/dev/null
+ # Explicit quality command definitions (key: value format)
+ grep -E "^(lint|test|check|format|typecheck|build):" "$CLAUDE_MD" 2>/dev/null
- # Look for Go tool references
- grep -E "(go vet|go test|golangci-lint)" .claude/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
+ ### Step 5: Detect Tech Stack and Extract Config
```bash
- # Check for common project files
- [ -f "pyproject.toml" ] && echo "python"
- [ -f "package.json" ] && echo "node"
+ # 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
```
### Step 6: Discover Verification Capabilities
```bash
+ # 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
- grep -E "^(dev-server|verify|e2e|smoke|health):" .claude/CLAUDE.md 2>/dev/null
+ [ -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 patterns
- cat package.json 2>/dev/null | grep -E '"(dev|start|serve)"'
+ # 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:
+ 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.
```markdown
## 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 |
- | custom-agent | project | [from agent description] |
+ | 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 |
- | capability-discovery | gh-workflow | This skill |
- | lint | project | Custom lint configuration |
+ | runtime-verification | gh-workflow | Runtime smoke/E2E testing |
+ | suggest-users | gh-workflow | Reviewer/assignee suggestion |
+ | custom-skill | project | [extracted from frontmatter] |
- ### Quality Commands (from CLAUDE.md)
- | Command | Purpose |
- |---------|---------|
- | `ruff check .` | Python linting |
- | `pytest` | Python tests |
- | `npm run lint` | JavaScript linting |
+ ### 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
+ ### In gh-start (Phase 3)
```markdown
- ## Phase 3: Capability Discovery
-
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-review
+ ### In gh-pr (Phase 1 Step 1.2)
```markdown
- ## Phase 2: Capability Discovery
+ 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)
+
+ ```markdown
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)
+
+ ```markdown
+ 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
+ ```
+
## 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` - Before implementation
- - `gh-review` - Before code review
- - `gh-address` - Before addressing feedback
+ - `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)
Results inform:
- - Which agents to delegate to
- - Which quality commands to run
- - How to adapt workflow to project
+ - 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. **Cache results** - Don't re-scan within same session
- 2. **Prefer explicit** - CLAUDE.md commands over detected ones
- 3. **Report clearly** - Show what was found and what wasn't
- 4. **Enable fallbacks** - Never block workflow due to missing capabilities
+ 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