From e6607cbe37846917e7ea6cdcba548505803f6cf1 Mon Sep 17 00:00:00 2001 From: Sarwagya Singh Date: Tue, 14 Jul 2026 03:19:43 +0200 Subject: [PATCH] Add Ontoly software graph skill --- README.md | 10 +- skill-finder.md | 5 +- .../codexkit-software-graph-analysis/SKILL.md | 107 ++++++++++++++++++ .../agents/openai.yaml | 5 + 4 files changed, 120 insertions(+), 7 deletions(-) create mode 100644 skills/codexkit-software-graph-analysis/SKILL.md create mode 100644 skills/codexkit-software-graph-analysis/agents/openai.yaml diff --git a/README.md b/README.md index d44cbf3..03dd80c 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ Open-source operating kit for people using OpenAI Codex and ChatGPT to think, write, analyze, decide, automate routine work, and ship better output with more consistency. -CodexKit is a fresh project rebuilt around the surfaces that matter in Codex today: local Skills, high-signal playbooks, automation recipes, operational templates, department starter workspaces, repo guardrails, and MCP onboarding guidance. The pack covers 90 skills across 15 work domains: engineering workflows, high-reasoning work, and low-reasoning office automation across project management, finance, legal, HR, operations, supply chain, strategy, analytics, marketing, data, customer success, sales, IT & admin, training & development, founder workflows, and cross-functional work. It follows the official Codex Skills layout with `SKILL.md`, optional `agents/openai.yaml`, and standard `.agents/skills` discovery paths. +CodexKit is a fresh project rebuilt around the surfaces that matter in Codex today: local Skills, high-signal playbooks, automation recipes, operational templates, department starter workspaces, repo guardrails, and MCP onboarding guidance. The pack covers 91 skills across 15 work domains: engineering workflows, high-reasoning work, and low-reasoning office automation across project management, finance, legal, HR, operations, supply chain, strategy, analytics, marketing, data, customer success, sales, IT & admin, training & development, founder workflows, and cross-functional work. It follows the official Codex Skills layout with `SKILL.md`, optional `agents/openai.yaml`, and standard `.agents/skills` discovery paths. ## What is included -- `skills/`: 90 installable Codex Skills across 15 work domains — engineering, high-reasoning business work, and low-reasoning office automation. +- `skills/`: 91 installable Codex Skills across 15 work domains — engineering, high-reasoning business work, and low-reasoning office automation. - `playbooks/`: copy-ready prompts for clarify, execute, review, decision, delegation, and release work. - `automations/`: 14 recurring task recipes for engineering plus weekly business, close, hiring, legal intake, operations, marketing, standups, meeting follow-ups, and OKR routines. - `mcp/`: practical guidance for choosing and rolling out MCP servers without overloading the team. @@ -36,7 +36,7 @@ If you do not want to use Git commands or remember terminal steps, use the GitHu 4. On Windows, double-click `START-HERE-WINDOWS.cmd`. - If Codex is not installed, the script will show installation instructions. 5. Restart Codex. -6. In Codex, type `/skills` to confirm all 90 skills appear. +6. In Codex, type `/skills` to confirm all 91 skills appear. 7. Open `skill-finder.md` to browse skills by situation. 7. Optional: double-click `CREATE-WORKSPACE-WINDOWS.cmd` to create a starter workspace. @@ -209,7 +209,7 @@ Every skill addresses five concerns: **Intent** (clear purpose), **Knowledge** ( | Tier | Structure | Current coverage | |------|-----------|------------------| -| **1** | `SKILL.md` + `agents/openai.yaml` | All 90 skills | +| **1** | `SKILL.md` + `agents/openai.yaml` | All 91 skills | | **2** | + `verification/` + `examples/` | 26 high-value skills | | **3** | + `templates/` + `scripts/` | 5 technical skills | @@ -220,7 +220,7 @@ Every skill addresses five concerns: **Intent** (clear purpose), **Knowledge** ( | `knowledge` | 17 | | `data` | 16 | | `scaffolding` | 16 | -| `runbook` | 10 | +| `runbook` | 11 | | `verification` | 9 | | `automation` | 9 | | `review` | 9 | diff --git a/skill-finder.md b/skill-finder.md index cc32389..3a11a59 100644 --- a/skill-finder.md +++ b/skill-finder.md @@ -1,6 +1,6 @@ # Skill Finder — "I need to… → Use this skill" -> Quick reference for all 90 CodexKit skills grouped by what you're trying to accomplish. +> Quick reference for all 91 CodexKit skills grouped by what you're trying to accomplish. --- @@ -14,7 +14,7 @@ | `data` | Read, process, analyze, or visualize data | 16 | | `automation` | Chain repeatable steps into workflows | 9 | | `verification` | Validate, audit, or test outputs against standards | 9 | -| `runbook` | Step-by-step procedures for recurring operational situations | 10 | +| `runbook` | Step-by-step procedures for recurring operational situations | 11 | | `infra` | Technical delivery, CI/CD, system checks, governance | 4 | > Each skill's `SKILL.md` frontmatter includes a `category` field. See `templates/SKILL-TEMPLATE.md` for authoring guidelines. @@ -161,6 +161,7 @@ | I need to… | Skill | What it does | |---|---|---| | Onboard to a new codebase | `codexkit-repo-onboarding` | Map runtime model, risk zones, first next steps | +| Answer codebase questions from a Software Graph | `codexkit-software-graph-analysis` | Uses Ontoly graph evidence for architecture, impact, routes, services, and dependencies | | Get started with MCP | `codexkit-mcp-onboarding` | Evaluate and phase MCP adoption | | Do a risk‑first code review | `codexkit-high-signal-review` | Bugs, regressions, missing tests, operational gaps | | Harden test coverage | `codexkit-test-hardening` | Edge cases and regressions without noisy tests | diff --git a/skills/codexkit-software-graph-analysis/SKILL.md b/skills/codexkit-software-graph-analysis/SKILL.md new file mode 100644 index 0000000..f8f53df --- /dev/null +++ b/skills/codexkit-software-graph-analysis/SKILL.md @@ -0,0 +1,107 @@ +--- +name: codexkit-software-graph-analysis +description: Use Ontoly to answer codebase architecture, dependency, route, service, and impact questions from a deterministic Software Graph. +version: 1.0.0 +category: runbook +--- + +# Software Graph Analysis + +Use this skill when a software question should be answered from repository structure, symbol relationships, framework concepts, dependency edges, or request-flow evidence instead of repeated file search. + +## Objectives + +- verify whether an Ontoly Software Graph already exists +- build or refresh the graph when it is missing or stale +- query Ontoly before opening source files +- cite graph evidence, node IDs, relationships, diagnostics, and confidence +- fall back to source inspection only when the graph cannot answer + +## Workflow + +1. Locate the repository root and check for `.ontoly/SoftwareGraph.json` or an explicitly supplied graph path. +2. If no graph exists, run `ontoly build .` from the repository root and capture diagnostics. +3. Check graph metadata, diagnostics, trust, coverage, and graph hash before relying on answers. +4. Use Ontoly CLI or MCP capabilities for the question: + - architecture or onboarding: architecture summary, packages, modules, services + - impact questions: impact analysis and dependency traversal + - request flow: route trace or execution trace + - configuration: configuration and environment-variable usage + - dead code: graph diagnostics and unreachable nodes +5. Produce the answer with evidence: relevant nodes, edges, source locations, diagnostics, and confidence. +6. Inspect source files only for missing graph coverage, ambiguous results, or verification of a suspected graph gap. +7. If Ontoly cannot answer, say exactly which graph evidence is missing and recommend a specific analyzer or graph-quality improvement. + +## Inputs + +| Input | Required | Format | +|-------|----------|--------| +| Repository path | Yes | Local path or current workspace | +| User question | Yes | Architecture, impact, route, dependency, or configuration question | +| Ontoly graph | Recommended | `.ontoly/SoftwareGraph.json` or generated by `ontoly build .` | +| Constraint | Optional | Package, framework, node name, route, or file path to focus on | + +## Output + +Produce a compact evidence-backed analysis: + +```markdown +## Software Graph Answer + +### Answer +{Direct answer in 1-3 paragraphs.} + +### Evidence +| Evidence | Source | +|----------|--------| +| Node | `{node id}` | +| Edge | `{source} --RELATIONSHIP--> {target}` | +| Location | `{file}:{line}` | + +### Confidence +{High, Medium, or Low} because {graph evidence and diagnostics}. + +### Gaps +{Missing coverage, ambiguous nodes, or source fallback used.} +``` + +## Quality Criteria + +- [ ] The answer starts from Ontoly graph evidence, not file search. +- [ ] Every major claim cites at least one node, edge, diagnostic, graph statistic, or source location. +- [ ] Confidence is derived from graph evidence and diagnostics, not guessed. +- [ ] Source inspection is explicitly labeled as fallback evidence when used. + +## Verification (4C) + +| Check | Question | +|-------|----------| +| **Correctness** | Does the answer match the graph nodes, relationships, source locations, and diagnostics? | +| **Completeness** | Are relevant callers, callees, dependencies, routes, modules, configuration, or services included for the question? | +| **Context-fit** | Does the explanation match the user's requested scope instead of dumping the full graph? | +| **Consequence** | If a developer acted on this answer, what could break if an edge or node was missing? | + +## Edge Cases + +- **Ontoly is not installed** — Ask to install it or use `npx ontoly build .` if the package is publicly available in the environment. +- **Graph build fails** — Report the command, exit code, diagnostics, and the smallest reproducible blocker. +- **Ambiguous node name** — List candidates with node IDs, kinds, and source locations before answering. +- **Low graph trust or coverage** — Answer only the evidenced part and recommend targeted graph validation before using the result for a change plan. +- **Repository is huge** — Start with architecture, package, module, and service summaries before expanding to functions. + +## Examples + +> **Good:** "AuthService depends on UserRepository through an INJECTS edge and is called by AuthController for POST /login. Confidence is High because the route, controller, service, and dependency edges all exist in the graph." + +> **Bad:** "I searched the repo and it looks like auth is probably in `src/auth`." This bypasses the Software Graph and gives no deterministic evidence. + +## Definition of Done + +- [ ] Ontoly graph existence and freshness checked. +- [ ] Relevant Ontoly query or MCP capability used. +- [ ] Answer includes graph evidence and confidence. +- [ ] Missing graph coverage is called out as a gap, not hidden by source search. + +## Changelog + +- v1.0.0 — Initial release diff --git a/skills/codexkit-software-graph-analysis/agents/openai.yaml b/skills/codexkit-software-graph-analysis/agents/openai.yaml new file mode 100644 index 0000000..5adeec9 --- /dev/null +++ b/skills/codexkit-software-graph-analysis/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Software Graph Analysis" + short_description: "Answer codebase questions with Ontoly graph evidence." + default_prompt: "Use $codexkit-software-graph-analysis to answer this repository question from Ontoly Software Graph evidence." + brand_color: "#2563EB"