From symantic
Use when navigating, reading, or tracing TypeScript/JavaScript source — understanding a file's shape, finding where a symbol is defined/used/implemented, tracing callers or callees, or about to Read a .ts/.tsx file or grep for a symbol in a project with a tsconfig. Redirects textual reads to semantic, name-addressed queries via the symantic CLI.
How this skill is triggered — by the user, by Claude, or both
Slash command
/symantic:using-symanticThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`symantic` gives semantic, token-lean, name-addressed views of TS/JS code — far cheaper and
symantic gives semantic, token-lean, name-addressed views of TS/JS code — far cheaper and
more precise than reading whole files or grepping for a name.
Before you Read a .ts/.tsx file, or grep for a symbol in a project that has a
tsconfig.json: stop and use symantic instead. Read on TS source is the textual habit
symantic replaces.
Invocation shape — tsconfig is auto-discovered from cwd:
symantic <op> <file>:Name
Pass --tsconfig <path> only to override discovery. If symantic is wired into the session as
an MCP server, prefer its MCP tools over shelling out — same ops, same addressing.
| Question | Command |
|---|---|
| Shape of this file? | symantic view outline <file> |
| Source of one declaration? | symantic view symbol <file>:Name (:: nests, e.g. Class::method) |
| Members of a class / interface / namespace? | symantic view members <file>:Name |
| Signature + callees + referenced types? | symantic view context <file>:Name |
| Where defined / used / implemented? | symantic find def|refs|impls <file>:Name |
| Who calls it / what does it call? | symantic find callers|callees <file>:Name |
| Find a symbol, file unknown — exact name? | symantic find symbol Name |
| Find a symbol, file unknown — only know part of the name? | symantic find symbol Foo --contains (substring; your orientation entry point) |
| A file's imports / public surface? | symantic imports <file> · symantic exports <file> |
Rest, briefly: view file (whole file, lean; --body for each export's source), view body
(statement skeleton of a function), view region <file>:Lstart-Lend, usage (per-export
reference counts), resolve (qualified name → symbol or candidates). Flags: symantic <cmd> --help.
file:Name — file is project-relative, forward-slashed.:: separates nesting segments (namespace / class / interface / module).#index disambiguates same-name collisions (overloads, declaration merging), e.g. f#1.view symbol <file>:Owner::member (or view members <file>:Owner)
returns just that member. A line-range view region / Read is a habit fallback here, not a
necessity.Example chain:
symantic view outline src/server.ts # see the shape
symantic view context src/server.ts:start # signature + callees + types of one decl
symantic find callers src/server.ts:start # who calls it
Append --engine lsp (tsgo-backed, faster on the hot path) to any command by default. Drop it
— back to the default ts-morph engine — if it errors that tsgo is unavailable, returns
empty/surprising results, or shows a parity gap. Known gap: find symbol on --engine lsp can
return empty where the default engine finds the symbol — if a name search comes back (none),
retry without --engine lsp before concluding the symbol doesn't exist.
symantic is not a grep replacement; the two compose. symantic addresses code by name, not by path or text — it has no file/directory enumeration. Use grep/find to orient, then symantic to understand:
Common trap: reaching for a shell find -iname '*foo*' to locate a feature. Try
symantic find symbol Foo --contains first — it searches symbol names across the project and
hands back addresses you can drill straight into. Fall to shell find only when you're after a
file path / non-TS file, not a symbol.
Orienting by concept, not a known name? (e.g. "where is data loading triggered?", "is
there a saga layer?") Don't grep the source — cast find symbol --contains with a broad
fragment of the concept (load, saga, dispatch, reducer) first. It surfaces every
matching symbol across the whole project, including layers in directories you haven't opened —
the exact case where grep makes you miss code that lives where you didn't look. Only grep the
concept when a sensible fragment genuinely yields nothing.
Tracing a whole flow? Cast for every layer's vocabulary, not just the first hit. An
end-to-end flow (UI → action → reducer/saga → server → render) spans several layers, each with
its own naming. Casting find symbol reducer/saga --contains finds the client-state half but
stops there — the server-data half lives under different words (provider, loader,
query, request, executePlan, fetch). Enumerate the layers you expect up front and
cast a fragment for each; a flow that "delegates to the framework" often still has a local
provider/loader doing the real work. The kind column (cls/fn/iface) on each --contains
hit is your cheapest orientation signal — a …Provider/…Loader class among fn hits is
often the server seam.
When a --contains cast drowns in test-file hits (*.test.ts, __tests__/, e2e/) on a
project whose tsconfig includes tests, add --exclude-tests to drop them — don't pipe the
output through grep -v test. When a fragment collides with unrelated symbols (e.g. action
matching ActionBar/RowAction components), narrow by declaration kind with
--kind cls,iface,fn,ns,const,type,enum instead of eyeballing a long list. To scope a cast
to one subtree (e.g. only view/ or server-connector/), add --path <substr> — don't
pipe through grep <dir>.
Only when symantic can't serve it: non-TS file, file outside the tsconfig project, no
tsconfig.json findable, symantic not installed, or no op fits a quick one-off. Don't force it.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub nam-hle/symantic --plugin symantic