Ontoly Software Graph
Overview
Ontoly builds a deterministic Software Graph from a TypeScript repository and exposes it through CLI queries, MCP capabilities, and agent skills. Use this skill when a coding agent needs evidence-backed codebase understanding before searching files directly.
This skill is an operating guide for the public Ontoly project. It does not contain compiler logic; all software understanding should come from Ontoly's generated graph, semantic model, query engine, and MCP server.
When to Use This Skill
- Use when the user asks for repository architecture, module ownership, or onboarding help.
- Use when tracing a request, route, controller, service, provider, dependency, or call chain.
- Use when estimating impact for removing, renaming, or refactoring a symbol, module, package, route, or service.
- Use when reviewing dependency topology, circular imports, dead code, configuration usage, or environment variables.
- Use when the user explicitly wants Ontoly, Software Graph, MCP, graph validation, semantic coverage, or agent skills.
How It Works
Step 1: Verify Ontoly Is Available
Check whether the repository already has Ontoly outputs such as .ontoly/, SoftwareGraph.json, validation reports, or documented Ontoly scripts. If the ontoly command is unavailable, ask the user whether to install or use the repository's documented package manager command.
Recommended local checks:
ontoly --help
find . -maxdepth 3 \( -name "SoftwareGraph.json" -o -name ".ontoly" \) -print
Step 2: Build or Refresh the Graph
Only run a graph build in the repository the user asked about. Tell the user that graph generation may create local Ontoly artifacts before running it.
ontoly build .
If the project documents a different command, prefer the documented command over guessing.
Step 3: Check Trust, Diagnostics, and Coverage
Before answering architectural questions, inspect Ontoly diagnostics, graph statistics, trust, and semantic coverage. Treat unresolved imports, low trust, missing framework detection, or graph validation failures as answer constraints.
Use the CLI or MCP capabilities exposed by the installed Ontoly version. Prefer structured graph queries over text search.
Step 4: Use Ontoly MCP Capabilities
Start or connect to the Ontoly MCP server when the host supports MCP:
ontoly mcp
Use capabilities such as architecture summaries, dependency analysis, request tracing, impact analysis, configuration lookup, framework reports, dead-code analysis, and graph validation when available.
Step 5: Answer With Evidence
Every answer should include:
- The Ontoly capability or query used.
- The node, edge, route, package, or diagnostic evidence that supports the answer.
- A confidence statement derived from graph evidence.
- Any known limitations caused by missing graph regions or diagnostics.
Step 6: Fall Back Gracefully
Only inspect repository files directly when Ontoly cannot answer, the graph is missing, diagnostics make the graph untrustworthy for the question, or the user asks for source-level verification. When falling back, explain which graph evidence was insufficient.
Examples
Architecture Review
User asks: "Explain this repository."
Workflow:
- Verify or build the Ontoly graph.
- Check graph trust, diagnostics, detected frameworks, packages, modules, services, routes, and largest dependency hubs.
- Use Ontoly's architecture summary or equivalent query.
- Report the architecture with graph evidence and confidence.
Request Tracing
User asks: "Trace the login flow."
Workflow:
- Search graph nodes for authentication routes and controllers.
- Trace route-to-controller-to-service-to-repository relationships.
- Include unresolved edges or missing relationships as limitations.
- Avoid opening source files unless the graph cannot identify the flow.
Impact Analysis
User asks: "What breaks if I remove UserRepository?"
Workflow:
- Locate the graph node for
UserRepository.
- Query callers, consumers, dependency injection edges, modules, routes, and packages that reference it.
- Separate direct dependents from transitive impact.
- Include confidence based on explicit graph relationships.
Best Practices
- Prefer Ontoly graph queries before grep, AST parsing, or broad file search.
- Keep graph evidence separate from inference.
- Treat diagnostics as part of the answer, not as noise.
- Use exact node IDs, route paths, package names, and relationship names when available.
- Rebuild the graph after large user changes before making claims about current architecture.
- Keep fallbacks narrow and explain why they were needed.
Limitations
- Ontoly does not replace compiler, test, or runtime validation.
- Graph quality depends on the Ontoly version, supported language frontend, repository setup, and diagnostics.
- Missing or partial framework detection lowers confidence for framework-specific answers.
- Do not claim a relationship exists unless it is present in the graph or clearly labeled as an inference.
- Stop and ask for clarification if the repository path, target graph, or requested analysis scope is ambiguous.
Security & Safety Notes
- Run Ontoly only on repositories the user is authorized to analyze.
- Do not send graph files, source code, environment variables, diagnostics, or repository metadata to external services unless the user explicitly requests it.
- Treat environment-variable nodes, configuration nodes, and diagnostics as potentially sensitive.
- Graph generation is local analysis but can create files such as graph output, diagnostics, indexes, or caches inside the repository.
- Do not execute project build scripts, package installation, or network commands unless they are documented by the repository or approved by the user.
Common Pitfalls
Problem: Answering from file search even though the graph already contains the relationship.
Solution: Query Ontoly first and use file inspection only as a fallback.
Problem: Reporting low-confidence inference as a graph fact.
Solution: Label the claim as inferred and cite the supporting graph evidence separately.
Problem: Ignoring diagnostics.
Solution: Include graph validation and compiler diagnostics when they affect confidence.
Related Skills
@developer-onboarding - Use for broad onboarding when Ontoly is unavailable.@sdk-dx - Use for SDK design and developer experience reviews after Ontoly identifies public APIs.@api-onboarding - Use for API-specific onboarding when route and operation evidence is available.
Source: sickn33/agentic-awesome-skills → skills/ontoly-software-graph/SKILL.md
Also appears in: sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills/skills/ontoly-software-graph/SKILL.md, sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills-claude/skills/ontoly-software-graph/SKILL.md
1---2name: ontoly-software-graph-23description: Use Ontoly's deterministic Software Graph, MCP server, and agent skills for architecture review, request tracing, impact analysis, and dependency analysis.4---5
6
7# Ontoly Software Graph
8
9## Overview
10
11Ontoly builds a deterministic Software Graph from a TypeScript repository and exposes it through CLI queries, MCP capabilities, and agent skills. Use this skill when a coding agent needs evidence-backed codebase understanding before searching files directly.
12
13This skill is an operating guide for the public Ontoly project. It does not contain compiler logic; all software understanding should come from Ontoly's generated graph, semantic model, query engine, and MCP server.
14
15## When to Use This Skill
16
17- Use when the user asks for repository architecture, module ownership, or onboarding help.
18- Use when tracing a request, route, controller, service, provider, dependency, or call chain.
19- Use when estimating impact for removing, renaming, or refactoring a symbol, module, package, route, or service.
20- Use when reviewing dependency topology, circular imports, dead code, configuration usage, or environment variables.
21- Use when the user explicitly wants Ontoly, Software Graph, MCP, graph validation, semantic coverage, or agent skills.
22
23## How It Works
24
25### Step 1: Verify Ontoly Is Available
26
27Check whether the repository already has Ontoly outputs such as `.ontoly/`, `SoftwareGraph.json`, validation reports, or documented Ontoly scripts. If the `ontoly` command is unavailable, ask the user whether to install or use the repository's documented package manager command.
28
29Recommended local checks:
30
31```bash
32ontoly --help
33find . -maxdepth 3 \( -name "SoftwareGraph.json" -o -name ".ontoly" \) -print
34```
35
36### Step 2: Build or Refresh the Graph
37
38Only run a graph build in the repository the user asked about. Tell the user that graph generation may create local Ontoly artifacts before running it.
39
40```bash
41ontoly build .
42```
43
44If the project documents a different command, prefer the documented command over guessing.
45
46### Step 3: Check Trust, Diagnostics, and Coverage
47
48Before answering architectural questions, inspect Ontoly diagnostics, graph statistics, trust, and semantic coverage. Treat unresolved imports, low trust, missing framework detection, or graph validation failures as answer constraints.
49
50Use the CLI or MCP capabilities exposed by the installed Ontoly version. Prefer structured graph queries over text search.
51
52### Step 4: Use Ontoly MCP Capabilities
53
54Start or connect to the Ontoly MCP server when the host supports MCP:
55
56```bash
57ontoly mcp
58```
59
60Use capabilities such as architecture summaries, dependency analysis, request tracing, impact analysis, configuration lookup, framework reports, dead-code analysis, and graph validation when available.
61
62### Step 5: Answer With Evidence
63
64Every answer should include:
65
66- The Ontoly capability or query used.
67- The node, edge, route, package, or diagnostic evidence that supports the answer.
68- A confidence statement derived from graph evidence.
69- Any known limitations caused by missing graph regions or diagnostics.
70
71### Step 6: Fall Back Gracefully
72
73Only inspect repository files directly when Ontoly cannot answer, the graph is missing, diagnostics make the graph untrustworthy for the question, or the user asks for source-level verification. When falling back, explain which graph evidence was insufficient.
74
75## Examples
76
77### Architecture Review
78
79User asks: "Explain this repository."
80
81Workflow:
82
831. Verify or build the Ontoly graph.
842. Check graph trust, diagnostics, detected frameworks, packages, modules, services, routes, and largest dependency hubs.
853. Use Ontoly's architecture summary or equivalent query.
864. Report the architecture with graph evidence and confidence.
87
88### Request Tracing
89
90User asks: "Trace the login flow."
91
92Workflow:
93
941. Search graph nodes for authentication routes and controllers.
952. Trace route-to-controller-to-service-to-repository relationships.
963. Include unresolved edges or missing relationships as limitations.
974. Avoid opening source files unless the graph cannot identify the flow.
98
99### Impact Analysis
100
101User asks: "What breaks if I remove UserRepository?"
102
103Workflow:
104
1051. Locate the graph node for `UserRepository`.
1062. Query callers, consumers, dependency injection edges, modules, routes, and packages that reference it.
1073. Separate direct dependents from transitive impact.
1084. Include confidence based on explicit graph relationships.
109
110## Best Practices
111
112- Prefer Ontoly graph queries before grep, AST parsing, or broad file search.
113- Keep graph evidence separate from inference.
114- Treat diagnostics as part of the answer, not as noise.
115- Use exact node IDs, route paths, package names, and relationship names when available.
116- Rebuild the graph after large user changes before making claims about current architecture.
117- Keep fallbacks narrow and explain why they were needed.
118
119## Limitations
120
121- Ontoly does not replace compiler, test, or runtime validation.
122- Graph quality depends on the Ontoly version, supported language frontend, repository setup, and diagnostics.
123- Missing or partial framework detection lowers confidence for framework-specific answers.
124- Do not claim a relationship exists unless it is present in the graph or clearly labeled as an inference.
125- Stop and ask for clarification if the repository path, target graph, or requested analysis scope is ambiguous.
126
127## Security & Safety Notes
128
129- Run Ontoly only on repositories the user is authorized to analyze.
130- Do not send graph files, source code, environment variables, diagnostics, or repository metadata to external services unless the user explicitly requests it.
131- Treat environment-variable nodes, configuration nodes, and diagnostics as potentially sensitive.
132- Graph generation is local analysis but can create files such as graph output, diagnostics, indexes, or caches inside the repository.
133- Do not execute project build scripts, package installation, or network commands unless they are documented by the repository or approved by the user.
134
135## Common Pitfalls
136
137- **Problem:** Answering from file search even though the graph already contains the relationship.
138 **Solution:** Query Ontoly first and use file inspection only as a fallback.
139
140- **Problem:** Reporting low-confidence inference as a graph fact.
141 **Solution:** Label the claim as inferred and cite the supporting graph evidence separately.
142
143- **Problem:** Ignoring diagnostics.
144 **Solution:** Include graph validation and compiler diagnostics when they affect confidence.
145
146## Related Skills
147
148- `@developer-onboarding` - Use for broad onboarding when Ontoly is unavailable.
149- `@sdk-dx` - Use for SDK design and developer experience reviews after Ontoly identifies public APIs.
150- `@api-onboarding` - Use for API-specific onboarding when route and operation evidence is available.
151
152---
153
154**Source:** [`sickn33/agentic-awesome-skills`](https://github.com/sickn33/agentic-awesome-skills) → `skills/ontoly-software-graph/SKILL.md`
155
156**Also appears in:** `sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills/skills/ontoly-software-graph/SKILL.md`, `sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills-claude/skills/ontoly-software-graph/SKILL.md`
sickn33