code-intelligence

Files (8)

• PROVENANCE.md
• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• trigger-queries.json · evals/
• degradation-and-disclosure.md · references/
• lsp-calls.md · references/
• tool-precedence.md · references/

SKILL.md (first lines)

# Code Intelligence

Pick the search tool by task, not by habit. Generic and language-agnostic —
domain skills may extend it with server capability matrices and ecosystem
prerequisites. This is model-triggered guidance, not enforcement.

## Use this skill when

- Navigating code: finding definitions, references, callers, or rename impact
- Choosing between LSP, `rg`, `grep`, or semantic search for a specific task
- An LSP call returns empty and you are unsure whether it represents failure or a degraded workspace
- A tool substitution or omission needs to be disclosed to the reader
- Verifying a tool is genuinely missing before falling back

## Do not use this skill when

- The task is pure text search for a known literal with no symbol-scope concern — use `rg` directly
- You are building a structural rewrite or codemod — use the `ast-grep` skill
- You need a pre-edit map of all files involved in a change — use the `context-map` skill

## Inputs to gather

**Required before querying**

- The symbol, file, or workspace to investigate.
- The LSP language (TypeScript, Go, Lua, Terraform, or YAML).

**Helpful if present**

- Whether a language server is available for the target file type.

## First move

1. Check that an LSP server is available for the target language.
2. Prefer LSP operations (goToDefinition, findReferences) over grep when available.
3. Fall back to grep/glob when no language server supports the file type.

## Routing boundary

| Situation | Use this skill? | Route instead |
|-----------|----------------|---------------|
| Navigating to a symbol definition or finding all references | Yes | — |
| Counting occurrences of an exact string | No | `rg` directly |
| Syntax-aware structural search or codemod | No | `ast-grep` |
| Mapping all files and tests before a broad edit | No | `context-map` |
| Terraform-specific LSP (terraform-ls) capability matrix | Partial | Defer ecosystem-specific setup to infrastructure skills |

## Tool Precedence

| Goal | Use | Tradeoff |
|------|-----|----------|
| Symbol relationships (definition, references, call sites, rename safety) | Language server (LSP) at a `file:line:character` position | Needs a running server + indexed workspace |
| Exact text, known name, exhaustive enumeration, config/value files | `rg` then Read | No semantic scope; matches strings in comments too |
| Conceptual / fuzzy / "where might this live" / cross-repo discovery | Semantic/neural search tool (if the host provides one) | Not exact; never use for counts or completeness claims |

Detail: [references/tool-precedence.md](references/tool-precedence.md#precedence-table)

## Calling the LSP

- **DO** call at a position (`file:line:character`). Anchor the position with a text search first.
- **DON'T** pass a bare symbol name and expect resolution — empty result = usage defect, not server failure.
- **DO** Read the returned locations for source text; LSP returns positions, not lines.
- **DO** retry once on cold start (server may be indexing).
- **DO** prefer the server's own `rename`/`prepareRename` for renames; call hierarchy for callers.
- **DON'T** report an unsupported operation as a finding — redirect instead.

Detail: [references/lsp-calls.md](references/lsp-calls.md#position-anchoring)

## Degradation Gate

Two cases before declaring LSP unavailable:

- **No LSP at all** (no tool exposed, server won't start) → genuine unavailability. Disclose on line 1 and use text search. Gate does not apply.
- **LSP callable but position-anchored call returns empty** → run all three checks before falling back:
  1. `documentSymbol` on an in-scope file returns symbols → server is responsive
  2. The failing call was position-anchored, not symbol-name-only
  3. That anchored call still returned empty after a cold-start retry

Only after all three pass is a disclosed text fallback warranted.

Detail: [references/degradation-and-disclosure.md](references/degradation-and-disclosure.md#degradation-gate)

## Disclose Substitutions

State any tool substitution or omission on the **first line** of the response:

```
Intended: <tool>. Actual: <tool>. Reason: <why>. Impact: <completeness/confidence>.
```

## Do Not Invent a Missing Tool

Before claiming a tool is shimmed, aliased, or absent, prove it:
`type -a <tool>`, `ls -l <resolved-path>`, `<tool> --version`. An unproven claim followed by a fallback is a verification failure, not a sanctioned substitution.

Detail: [references/degradation-and-disclosure.md](references/degradation-and-disclosure.md#anti-phantom-shim-proof)

## Workflow

1. Identify the language and whether an LSP server is available for the target files.
2. Prefer LSP: go-to-definition, find-references, hover, rename, diagnostics.
3. If LSP returns empty or unsupported, disclose the fallback and switch to `rg`/glob with a tighter scope.
4. For semantic "what does this do" questions without a stable symbol, use semantic search after LSP/grep miss.
5. Never invent symbols, call graphs, or unused-status claims without tool evidence.
6. When refactoring, confirm references via LSP before mass edits; re-run diagnostics after.
7. Summarize which tool answered each claim so the user can trust the navigation trail.

## Guardrails

- **Must not** invent symbol definitions or call relationships not found by a tool.
- **Should** prefer code intelligence tools over text search for semantic queries.
- **Should** disclose when falling back from LSP to grep/glob and why.
- **Should** not claim a symbol is unused unless a language server confirms no references.

## Validation

**Should trigger this skill:**
- "Find all callers of `parseConfig` in the Go codebase"
- "Rename `UserSession` everywhere it's used safely"

From matt-riley/agent-skills, GPL-3.0.

More from matt-riley/agent-skills