Skip to content

feat(skills): add UModel agent skills — umodel-query + umodel-rca (CLI-first)#37

Open
qiansheng91 wants to merge 5 commits into
mainfrom
codex/agent-investigation-skill
Open

feat(skills): add UModel agent skills — umodel-query + umodel-rca (CLI-first)#37
qiansheng91 wants to merge 5 commits into
mainfrom
codex/agent-investigation-skill

Conversation

@qiansheng91

@qiansheng91 qiansheng91 commented Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Add a top-level, publishable skills/ tree with two loadable agent skills that let an MCP/CLI-connected agent (Claude Code / Cursor / Qoder) use a UModel object-graph semantic layer. CLI-first (umctl), MCP noted as an alternative.

skills/
├── README.md / README.zh-CN.md     # catalog: what a skill is, how to load one, how to author one
├── umodel-query/SKILL.md           # read data + read model
└── umodel-rca/SKILL.md             # model-guided root-cause analysis

The two skills (mapped to the three things an agent does with UModel)

  • umodel-query — reads: (1) entity & relationship/topology data (.entity / .topo) and (2) the UModel model itself (.umodel + __list_method__ / list_data_set). Returns real rows in open source; against a PaaS-backed endpoint the same commands return the PaaS API's data.
  • umodel-rca — (3) model-guided fetch (get_metrics / get_logs, driven by the object graph so service_id is auto-filled; a plan in open source, data via a PaaS endpoint) plus an autonomous root-cause loop (orient → fetch → hypothesize → multi-hop / cross-domain evidence → discriminate → conclude) and runbook-as-scaffold. Builds on umodel-query.

Splitting keeps each skill's description tight for precise activation.

Why top-level skills/ (not examples/)

These are publishable artifacts, so they live in a dedicated top-level tree, not buried in a sample pack. Side benefit: keeping non-model files out of examples/incident-investigation/ stops the sample importer from choking on them (make quickstart stays healthy). A separate follow-up will make the importer skip non-model files regardless.

Docs

  • skills/README.md + skills/README.zh-CN.md — catalog: what a skill is, prerequisites, how to load skills into an agent, how the two relate, and how to author a new skill.
  • Linked from the root README (en/cn) and docs index (en/zh) under a new Agent Skills entry; cross-linked to the Agent Integration Guide.

Verification

Every command in both skills was run against the latest main demo server (make quickstart QUICKSTART_SAMPLE=examples/incident-investigation):

  • .entity → real entity rows; .topo → real relation rows; .umodel → real model metadata
  • __list_method__ / list_data_set → method & dataset discovery
  • get_metrics → renders P99 PromQL with service_id substituted (plan in OSS)
  • Response shape documented for parsing (rows = data.data, columns = data.header)

Out of scope

  • Importer robustness (skip non-model files) — separate follow-up.

@qiansheng91 @claude
feat(examples): add autonomous-investigation agent skill (v1)
6af61f0 
A standalone, loadable SKILL.md that teaches an MCP-connected agent to do
AUTONOMOUS root-cause analysis over a UModel object graph — not a scripted
walkthrough. It gives the agent the method (orient → autonomous retrieval →
hypothesize → gather multi-hop/cross-domain evidence → discriminate root
cause from coincidence → conclude) and the query-surface toolkit, then lets
the agent choose its own path. The incident-investigation demo is the worked
example / test bed, not a script to replay.

Complements the runbook's embedded incident-investigation skill (which is
demo-specific and step-ordered): this one is reusable and decision-driven.

The MCP client config is embedded in the SKILL.md as a code block (no
separate config file — a non-model .json in a sample pack breaks the
importer's recursive element scan).

Verified on latest main: all 10 query patterns the skill teaches return
the expected results against `make quickstart
QUICKSTART_SAMPLE=examples/incident-investigation`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@qiansheng91 qiansheng91 added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 11, 2026
@qiansheng91 @claude
refactor(examples): redesign agent skill — CLI-first, three capabilities
fb74250 
Reframe the skill around the three things an agent actually does with
UModel, and make the umctl CLI the primary transport (MCP demoted to an
alternative note):

1. Read entity & relationship/topology data (.entity / .topo) — returns
   real rows in open source; against a PaaS-backed endpoint the same
   commands return the PaaS API's data response.
2. Read the UModel model itself (.umodel + __list_method__ / list_data_set)
   — the "map" of object types, datasets, links, runbooks.
3. Model-guided data fetch + root-cause analysis — get_metrics / get_logs
   driven by the object graph (service_id auto-filled; plan in OSS, data
   via PaaS mode=data), plus the autonomous RCA loop and runbook scaffold.

Documents the real `umctl query run <ws> "<SPL>" -o json` form and the
actual response shape (rows in data.data, columns in data.header) so an
agent can parse results. Every command verified against the latest main
demo server.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@qiansheng91 qiansheng91 changed the title feat(examples): add autonomous-investigation agent skill feat(examples): add UModel agent skill (CLI-first: read data, read model, RCA) Jun 11, 2026
@qiansheng91 @claude
refactor(skills): move agent skill to top-level skills/ + add catalog…
9bc7a2d 
… docs

The agent skill is a publishable artifact, so it should not live under
examples/. Move it to a dedicated top-level skills/ tree and document it:

- skills/umodel/SKILL.md  (moved from examples/incident-investigation/skill/)
- skills/README.md + skills/README.zh-CN.md — the skills catalog: what a
  skill is, prerequisites, how to load one into Claude Code / Cursor /
  Qoder, how the umodel skill is organized, and how to author a new one.
- Linked from the root README (en/cn) and docs index (en/zh) under a new
  "Agent Skills" entry, and cross-linked to the Agent Integration Guide.

Side effect: moving the skill out of the sample-pack directory also stops
it from breaking `make quickstart` — the importer recursively scans a
pack dir and chokes on any non-model file. (A separate follow-up will
make the importer skip non-model files regardless.)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@qiansheng91 qiansheng91 force-pushed the codex/agent-investigation-skill branch from 7c5b8aa to 9bc7a2d Compare June 11, 2026 07:40
@qiansheng91 @claude
refactor(skills): split into umodel-query and umodel-rca
8064df9 
A published skill should be scoped to one job and trigger precisely, so
split the single broad umodel skill into two, matching the three things an
agent does with UModel:

- skills/umodel-query/  — read entity / relationship / topology data AND
  the UModel model (.entity / .topo / .umodel, __list_method__,
  list_data_set). Real rows in OSS; PaaS API data against a PaaS endpoint.
- skills/umodel-rca/    — model-guided autonomous root-cause analysis:
  get_metrics / get_logs fetch (plan in OSS / data via PaaS) + the
  autonomous investigation loop + runbook scaffold. Builds on umodel-query.

This keeps each skill's `description` tight (better activation: a "query
the topology" prompt shouldn't pull in the whole RCA method, and vice
versa), while the RCA skill reuses the query toolkit.

Updated the skills catalog (skills/README.{md,zh-CN.md}) to list both and
explain how they relate. Root README + docs index entries already describe
the collection and need no change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@qiansheng91 qiansheng91 changed the title feat(examples): add UModel agent skill (CLI-first: read data, read model, RCA) feat(skills): add UModel agent skills — umodel-query + umodel-rca (CLI-first) Jun 11, 2026
@qiansheng91 @claude
docs(skills): add end-to-end quickstart for using the skills with an …
6318c4e 
…agent

Close the last-mile gap to actually using the skills. New
skills/QUICKSTART.{md,zh-CN.md} walks a user through, with the bundled
incident-investigation pack as the demo object graph (entities + relations
+ model + runbook):

1. Install the skills — Claude Code native skills dir; or include SKILL.md
   as context for agents without a loader (Qoder / Codex).
2. Initialize the demo data — load the in-memory object graph via
   --quickstart-sample (no DB, no key, no network); CLI sanity checks.
3. Connect your agent — verified MCP configs for Claude Code (.mcp.json),
   Qoder (Settings → MCP → Add), and Codex (~/.codex/config.toml
   [mcp_servers.umodel]); plus the CLI path.
4. Ask questions — example prompts that activate umodel-query (reads) vs
   umodel-rca (root-cause analysis), and what the agent does.

Plus a troubleshooting section. Linked prominently from the skills catalog.

Per-tool MCP config formats confirmed against each tool's current docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@qiansheng91