---
name: steering-matcher
description: Match file paths against steering file glob patterns to determine applicable steering guidance. Use when you say "match steering for these files", "which steering applies to this task", or "inject steering context". Use when orchestrator needs to inject context-aware guidance based on files being modified. Do NOT use for reading steering files directly when the applicable file is already known; read the file manually instead.
license: MIT
metadata:
  routing:
    role: nested-helper
    invoker: context-gather
    trigger: context-gather runs steering-matcher as a sibling preflight skill in the build chain
    user-facing: false
version: 1.0.0
---

# Steering File Matcher Skill

## Triggers

| Trigger Phrase | Operation |
|----------------|-----------|
| `match steering for these files` | get_applicable_steering.py |
| `which steering applies to this task` | Pattern match against changed files |
| `inject steering context` | Return applicable steering sorted by priority |

## Purpose

This skill helps orchestrator determine which steering files to inject into agent context based on the files being modified.

- Match file paths against glob patterns in steering file front matter
- Return applicable steering files sorted by priority
- Enable token-efficient context injection (30%+ savings)

## When to Use

Use this skill when:

- Orchestrator needs to inject context-aware steering based on files being modified
- You want to scope agent guidance to only relevant files (token optimization)
- Matching file paths against `applyTo` glob patterns in steering front matter

Use manual file reading instead when:

- You already know which steering file applies
- The task affects a single known steering domain

## Quick Usage

### Using get_applicable_steering.py Script

The script in `.claude/skills/steering-matcher/scripts/get_applicable_steering.py` handles pattern matching.

```bash
# Match files against steering patterns
python3 .claude/skills/steering-matcher/scripts/get_applicable_steering.py \
    --files "src/claude/analyst.md" ".project-toolkit/security/TM-001-auth-flow.md" \
    --steering-path ".agents/steering"

# Output: JSON array of objects with name, path, apply_to, priority
```

## Process

This skill integrates with the orchestrator workflow:

1. **Task Analysis**: Orchestrator identifies files affected by task
2. **Pattern Matching**: Use this skill to find applicable steering
3. **Context Injection**: Include matched steering in agent prompt
4. **Token Optimization**: Only inject relevant guidance

### Standard Orchestrator Workflow

```bash
# 1. Identify files from task
# 2. Get applicable steering
python3 .claude/skills/steering-matcher/scripts/get_applicable_steering.py \
    --files "src/claude/security.md" ".project-toolkit/security/SR-001-oauth-review.md"

# 3. Inject into agent context
# Output: JSON with name, path, apply_to, priority sorted by priority descending
```

## Implementation

See `scripts/get_applicable_steering.py` for the Python implementation.

## Testing

Run pytest from a repository checkout to verify pattern matching (tests do not ship in plugin installs):

```bash
uv run pytest tests/skills/steering-matcher/ -q
```

## Anti-Patterns

| Avoid | Why | Instead |
|-------|-----|---------|
| Hardcoding steering file paths | Bypasses pattern matching, breaks on restructuring | Use get_applicable_steering.py |
| Injecting all steering files | Token bloat, irrelevant context | Match against changed files only |
| Ignoring priority ordering | Lower-priority guidance may contradict higher | Process results in priority order |

## Verification

After execution:

- [ ] Returned steering files match the `applyTo` patterns for the given files
- [ ] Results are sorted by priority (highest first)
- [ ] No duplicate steering entries in output

## Scripts

### get_applicable_steering.py

Matches file paths against steering glob patterns and returns applicable guidance.

```bash
python3 .claude/skills/steering-matcher/scripts/get_applicable_steering.py --files <file1> [<file2> ...]
```

## Related

Backticked paths below are in the `rjmurillo/ai-agents` repository. They do not ship with this skill; a consumer install cannot resolve them.

- `.agents/steering/README.md`. Steering system overview.
- `.agents/archive/planning/enhancement-PROJECT-PLAN.md`. Enhancement project plan.

The `orchestrator` agent consumes steering matches. It ships in the same plugin as this skill; invoke it by name rather than by path.

<!-- vendor-portability: declared. This skill links .agents/steering/README.md and .agents/archive/planning/enhancement-PROJECT-PLAN.md as documentation. Both are citations; the matcher reads the steering files the consumer repo actually has, and a vendored install loses only the broken links. Issue #2050. -->