@locusgraph/locus-skills-cli

Store skills as graph modules and compile a narrow SKILL.md on demand.

A skill written once is decomposed into modules and stored in a LocusGraph graph. When an agent needs it, locus compile retrieves only the modules that request actually calls for, so the session pays for the part it uses rather than the whole document.

Install

npm i -g @locusgraph/locus-skills-cli
locus login

locus login opens a device-code approval in the browser and stores a token; the CLI talks to the API and holds no graph credentials of its own.

Commands

| Command | What it does | | --- | --- | | locus new <slug> | scaffold library/<slug>/ — a SKILL.md and its artifact files, already admissible | | locus suggest <file> | turn messy input into a conformant SKILL.md under library/ | | locus lint [slug] | the verdict publish would give, without writing anything | | locus publish [slug] | seed library/<slug>/ into the graph — adds, never removes; the folder stays | | locus compile "<request>" | retrieve what the request needs and write .locus/<parent>/<view>/ — a view of the skill, named by what it holds, with every file it names | | locus skills [--brief] | every skill with its description, trigger phrases and sections; --brief is one line per skill, what the session hook prints | | locus show <slug> [<section> \| --all] | the skill as stored, by name: the map of sections, one section's text, or all of it. No compile, nothing written | | locus learn "<fact>" | the sections that could hold a fact, likeliest first, each with the learn update that writes it — free text never writes; --within <slug> to scope, --source <who> when it wasn't you (tool, document, assistant, derived) | | locus learn add\|append\|update\|delete\|merge … | the operators that write. append adds and never loses a line; update replaces and refuses a shorter body without --replace, then prints what changed. --topic sets the line retrieval matches on, --force overrides the archetype guard on delete and merge; see locus learn | | locus promote <view> --as <slug> | a compiled view becomes a skill of its own, related_to its parent | | locus promote <parent> --modules a,b --as <slug> | the same, naming the sections outright — no compiled view needed | | locus forget <slug> --yes | remove a skill and every locus under it, including anything added since it was seeded | | locus doctor | check auth and API reachability | | locus logout | discard the stored token |

Two directories, never the same one: library/ is where a skill is written and seeded from; .locus/ is what a compile writes: one directory per view, rebuilt when that view recompiles.

Compiling into a session

locus compile "review this auth change"
locus compile "review this auth change" --install claude --scope project

Without --install, the compile lands in .locus/<parent>/<view>/ with every referenced file beside it and executables kept executable. --install writes to the path the host reads (claude, codex or agent) instead; --within a,b narrows retrieval to named skills.

Options

| Flag | On | What it does | | --- | --- | --- | | --archetype <name> | new | the shape the skill is scaffolded to; procedural by default | | --category <name> | new | the category recorded on the skill; general by default | | --out <dir> | compile | write the compiled view somewhere other than .locus/ | | --within a,b | compile | narrow retrieval to named skills | | --install <host> | compile | pin the result where a host reads it — claude, codex or agent | | --scope <where> | compile | project (default) or global, for --install | | --yes | forget, learn delete | confirm a removal | | --api <url> | login | point at a different API host | | --version, -v | — | print the version |

locus learn documents its own operators and their flags — run it with no arguments.

Links

• Docs: https://skills.locusgraph.com/docs
• Claude Code plugin: @locusgraph/claude-locus-skills-plugin

MIT