p10ns11yp10ns11y/skills/shell-kernel-ontology/SKILL.md

shell-kernel-ontology

Skill2 starsChanged 40 days agoMITView on GitHub

Load and maintain the shellyxz shell kernel ontology graph — PATH contract, kernel/plugin boundary, load order, and verification bridge (ab/av/at). Use when editing ~/.config/shell core/, plugins/verification/, bin shims, moving files across the kernel boundary, or answering where a concept lives.

In this repository49 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adversarial-auditSkill
- agentic-reactorSkill
- agent-orchestratorSkill
- ai-optimizationSkill
- architecture-synthesisSkill
- audit-allow-buildsSkill
- audit-ide-dependenciesSkill
- author-workflow-skillSkill
- bdd-strategizerSkill
- chrome-extension-mv3Skill
- concurrent-cli-agentsSkill
- control-feederSkill
- control-graphSkill
- cursor-transcript-harvestSkill
- cv-promote-guardSkill
- devcontainer-hardenedSkill
- dual-copy-skill-publishSkill
- explore-repo-readonlySkill
- finder-reactorSkill
- fix-dependency-securitySkill
- fusion-sageSkill
- git-worktreesSkill
- grok-host-prepSkill
- gt-flowSkill
- higher-order-decision-architectSkill
- looperSkill
- master-plannerSkill
- mvu-refactor-planSkill
- odysseus-navigatorSkill
- project-editor-profileSkill
- react-client-expertSkill
- semantic-markup-cssSkill
- semantic-nameSkill
- session-unit-orderSkill
- skill-rename-propagationSkill
- split-to-prsSkill
- src-tree-reorganizeSkill
- stellar-roadmapSkill
- stellar-spacemapSkill
- subagent-delegationSkill
- subagent-explore-reportSkill
- supply-chain-hardenSkill
- tauri-agenticSkill
- tauri-ipc-debugSkill
- tidy-commit-pushSkill
- upgrade-packagesSkill
- verification-cockpitSkill
- x-agent-resourcesSkill

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Add or rename public hooks (path_contract_*, verify_workflow_root, resolver)
line 45
Distinctive:
After structural PR: run drift gate before merge
line 47
Distinctive:
When loading a subgraph, always retain:
line 72
Very specific:
Update code + PLUGIN.md / architecture.md if boundary semantics shift
line 100
Very specific:
Update shell-kernel.graph.yaml (nodes, source_refs, Artifact path)
line 101

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Shell Kernel Ontology

Portable skill — install from the agent skills library (shell-kernel-ontology/). Target repo: ~/.config/shell (shellyxz kernel).

Mission: Route agents to addressable semantics instead of re-inferring from scattered prose.

Asset	Live path
Graph	`~/.config/shell/.agents/ontology/shell-kernel.graph.yaml`
Index	`~/.config/shell/.agents/ontology/INDEX.md`
Viz	`~/.config/shell/.agents/ontology/GRAPH.md`
Fusion cache	`~/.config/shell/.agents/ontology/fusion-state.json`
HODA overlay	`~/.config/shell/arch-design/overlays/shell-kernel-decision-hooks.md`

Companion overlay: examples/overlays/shellyxz-shell-kernel.md

Adopt in ~/.config/shell

SKILLS_ROOT=~/Work/personal/skills   # or your skills clone
mkdir -p ~/.config/shell/.cursor/skills
ln -sfn "$SKILLS_ROOT/shell-kernel-ontology" ~/.config/shell/.cursor/skills/shell-kernel-ontology
# or symlink .agents/skills if your shell repo uses that layout

Open ~/.config/shell in Cursor, then invoke this skill when editing kernel/plugin structure.

When to use

Edit core/, plugins/verification/, bin/* shims, or path.contract layers
Move files across kernel vs verification plugin boundary
Add or rename public hooks (path_contract_*, verify_workflow_root, resolver)
User asks: "where does X live?", "kernel or plugin?", "update ontology"
After structural PR: run drift gate before merge

Do not use for: per-project .agents/verification/ cockpits in other repos — use verification-cockpit skill there.

Subgraph router (load by intent)

Intent	Start node	Load when
`path`	`shellyxz:PathContractDomain`	PATH contract, `path-resolve.sh`, lexicon locals
`boundary`	`shellyxz:KernelPluginBoundary`	Kernel vs plugin, `must_not` / `may_assume`, PLUGIN.md
`load_order`	`shellyxz:LoadOrder`	env.sh, zshrc tail, direnv `phase:project`
`verify`	`shellyxz:VerificationBridge`	ab/av/at, shims, resolver, cockpit-mcp, strict PATH

cd ~/.config/shell
bin/render-ontology-graph.sh --subgraph verify
bin/render-ontology-graph.sh --subgraph boundary

Never compress (ai-optimization)

When loading a subgraph, always retain:

Invariant nodes (shellyxz:Inv_*) tied to your edit
must_not / may_assume on boundary nodes
Public path_contract_* signatures and resolver function names
source_refs for nodes you cite in the PR

Verification bridge

Verb	Function	Resolver target
`ab`	`agent_build`	`verification_script_path agent-build-layout.sh`
`av`	`agent_verify`	`verification_script_path agent-verify-layout.sh`
`at`	`agent_test`	`verification_script_path agent-test-layout.sh`

Implementation: plugins/verification/ · Stable entry: bin/* shims
Headless: bin/cockpit-mcp.sh (plugin copy is canonical)
Per-repo manifest: .agents/verification/cockpit.yaml (in each repo, not kernel-only)
Strict PATH: SHELL_AGENT_STRICT_PATH=1 or ab --strict

Maintenance workflow

Structural change in one PR:

Update code + PLUGIN.md / architecture.md if boundary semantics shift
Update shell-kernel.graph.yaml (nodes, source_refs, Artifact path)
Refresh INDEX.md checklist row if needed
Run drift gate:

cd ~/.config/shell
bin/check-ontology.sh
bin/check-shell.sh --audit

Optional: regen Mermaid — bin/render-ontology-graph.sh --subgraph all

Extract-only facts file (local, gitignored): bin/extract-ontology-facts.sh

Companion skills

Skill	Role
verification-cockpit	Per-project tmux layouts (not kernel ontology)
stellar-spacemap	Backlog cards SN-* after ontology ships
fusion-sage	Fused abstractions in `fusion-state.json`

Plain rule: graph and tree move together — same discipline as architecture.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free