Navigate software architecture using semantic knowledge graphs

This skill is an operating guide for Ontoly's deterministic Software Graph. It helps a coding agent understand a TypeScript repository through the generated graph, semantic model, query engine, and MCP server before searching files directly. The guide contains no compiler logic of its own: software understanding comes from Ontoly's outputs and queries.

Its analysis workflows cover repository architecture, module ownership, onboarding, request tracing, and impact assessment. Architecture review examines detected frameworks, packages, modules, services, routes, and major dependency hubs. Request tracing follows route, controller, service, and repository relationships. Impact analysis locates a target graph node, checks callers, consumers, dependency injection edges, modules, routes, and packages, and separates direct dependents from transitive effects.

The guide also addresses dependency topology, circular imports, dead code, configuration usage, and environment variables. Queries should precede broad text search or AST parsing when the graph can answer the question. Graph evidence and inference remain distinct, so a relationship should be reported as a fact only when the graph contains it.

Use this workflow when explaining a repository, investigating a route or call chain, or assessing removal, renaming, or refactoring of a symbol, module, package, route, or service. Begin by checking for existing Ontoly artifacts or documented scripts. If the command is unavailable, ask whether to install it or use the repository's documented package manager command. Prefer project-documented commands over guesses.

Check diagnostics, statistics, trust, and semantic coverage before answering. Unresolved imports, missing graph regions, low trust, validation failures, or partial framework detection constrain the answer's confidence. Ontoly does not replace compiler, test, or runtime validation. Rebuild after substantial changes before describing current architecture.

Inspect source files directly when the graph is missing, cannot answer, is untrustworthy for the question, or the user requests source-level verification. Keep that fallback narrow and explain the missing evidence. Clarify ambiguous repository paths, target graphs, or analysis scope before proceeding.

Inputs are the authorized repository, its Ontoly artifacts, and a question identifying the architectural area or change under investigation. Existing outputs may include .ontoly directories, SoftwareGraph.json files, validation reports, and repository-defined Ontoly scripts. Build or refresh the graph only within the requested repository, informing the user that generation can create local artifacts:

ontoly build .

Each answer should identify the capability or query used and the supporting node, edge, route, package, or diagnostic evidence. Include confidence derived from that evidence and limitations caused by diagnostics or missing regions. Use exact node identifiers, route paths, package names, and relationship names when available.

Ontoly exposes CLI queries, MCP capabilities, and agent skills. When the host supports MCP, the guide describes connecting to its MCP server. Use the capabilities exposed by the installed version, including architecture summaries, dependency analysis, request tracing, impact analysis, configuration lookup, framework reports, dead-code analysis, and validation when available.

Graph files, source code, environment variables, diagnostics, and repository metadata must remain local unless external sharing is explicitly requested. Configuration and environment-variable nodes can contain sensitive information. Generation can create graph output, diagnostics, indexes, or caches. Run only on authorized repositories, and execute package installation, project build scripts, or network commands only when documented or approved.

Ontoly uses the MIT license.