Skills And Agents

Skills and Agents

Hypha's conversational surface is built from Claude Code skills (skills/), backed by subagents (agents/) for work that would otherwise pull too much into the main conversation's context, plus one slash command (commands/) and one hook (hooks/).

Skills

Skill	Triggers on	Does
metamodel-lookup	A question about how a SysML v2/KerML metaclass (e.g. PartUsage, Feature) is defined, or how elements relate	Reads knowledge/<tag>/metamodel/elements/<Name>.md and queries metamodel.json (via jq) for structural/set questions; cites cross-references.json for the governing clause and grammar production
model-library-lookup	A qualified standard-library name (ISQBase::mass, ScalarValues::Real, Parts::Part)	Resolves it via knowledge/<tag>/model-library/index.json and quotes the verbatim library source from packages/<slug>.md. Does not resolve :>/:>> redefinition/subsetting chains itself
spec-citation	A request for exact normative SysML v2/KerML spec wording	Quotes verbatim from knowledge/<tag>/spec/{kerml,sysml2}/, attributed as <document> <version> §<clause> <title> (p. <pages>); degrades to naming the governing clause via cross-references.json when the spec text itself is not installed
sysml-validation	Inline .sysml/.kerml notation to check	Validates syntax against the grammar and structure against the metamodel (reachability, lower<=upper multiplicity) using metamodel.json; reports findings as Location / Rule / Why / Fix / Reference
version-management	A question about available or installed releases, or a report from the SessionStart hook	The conversational vocabulary over the hypha CLI (check, discover, fetch, generate, use, remove); always confirms before a fetch or a remove

Every skill shares the same conventions:

• Knowledge is read per release tag (knowledge/<tag>/...); a skill reads knowledge/versions.json for the default tag first and states which release it answered from.

• Every fact carries one of three provenance tiers, so a reader can tell what was read verbatim from what was inferred:

  Tier	Meaning
  NORMATIVE	Verbatim, clause-anchored specification text
  MODEL	Read directly from the metamodel XMI or the model library source
  DERIVED	Computed by the generation pipeline – inheritance closures, name-matched cross-references

  The tier definitions travel with the data itself, in the provenanceTiers block of cross-references.json.

Each skill's procedure names when to hand off to its corresponding subagent, typically "only when the answer still needs many element files read."

Agents

Agent	Tools	Job
metamodel-navigator	Read, Grep, Glob	Breadth/fan-out sweeps over the metamodel knowledge base (e.g. "which metaclasses have a feature typed by Expression") so bulk file reads stay out of the caller's context; queries metamodel.jsonviajq` first, falls back to Grep/Glob
spec-citation	Read, Grep, Glob	Multi-clause gathering and cross-referencing of normative spec text, for questions spanning more clauses than fit in the skill's own turn
sysml-validator	Read, Grep, Glob	Validates larger textual-notation inputs than the inline skill handles comfortably, using the same syntax/structural checks and the same findings format

Commands

/overview (commands/overview.md) shows a fixed, verbatim overview of Hypha's three capabilities: metamodel lookup, spec citation, validation; with example prompts. It never triggers automatically (disable-model-invocation: true); it only runs when a user types it.

As of hypha 1.3.0/plugin v2.1.0, spec citation no longer needs the PDFs placed or tools/spec-extract run manually – hypha fetch downloads them by default and hypha generate extracts them via uv on its own (see Generation Pipelines#tools-spec-extract). commands/overview.md's own wording still describes the old manual steps; see if it's been refreshed to match before trusting it verbatim.

The SessionStart hook

.claude-plugin/plugin.json registers one hook, SessionStart (matcher startup|resume), whose command is a one-line POSIX shell dispatch that execs the right platform binary under hooks/native/<rid>/hypha-hook[.exe], chosen from uname -s/uname -m (Linux, Darwin arm64/x64, MINGW/CYGWIN/MSYS for Windows). The hook entry pins "shell": "bash", so Claude Code always runs this dispatch under a real bash instead of falling back to PowerShell (which can't parse it) – on Windows this means Git for Windows (Git Bash) is required; without it Claude Code reports a clear "shell not found" error rather than a parse error. hooks/native/ is populated only by the hook-binaries.yml workflow (see Build and Release), never by hand.

The binary itself is a separate, NativeAOT-published project, Hypha.Tools.Hook, small (single-digit MB) and free of the dependencies that would otherwise block ahead-of-time compilation. Each session start it:

1. Downloads and checksum-verifies the pinned hypha CLI version (plugin.json's hyphaCliVersion field) from GitHub Releases the first time it is needed, caching it outside the plugin's git-managed folder so plugin updates never disturb it.
2. Runs hypha check --json synchronously – a cheap, read-only comparison that never fetches, generates, or deletes anything, well inside SessionStart's default timeout.
3. Feeds one line of additionalContext back to Claude: nothing installed (names the upstream options), a newer release exists (names it), or nothing at all if there is nothing to report.

See Hypha CLI for the hypha check command itself, and Build and Release for how the hook binaries are built and shipped.