README · 516933d98f9d

skill-lib

A portable library of agent skills built on msdmd — Module Self- Declared Metadata in Markdown. MSDMD consumes metadata already expressed in native code, documentation, manifests, schemas, tooling, and evidence formats; its own comment blocks supplement information not already expressed adequately. The foundational skill and convention catalogue define the native-first contract. The shipped collector currently implements the narrower MSDMD-block path; listed conventions are not claims of implemented readers.

Licensed under MPL-2.0 (relicensed from MIT; weak copyleft — embed anywhere, changes to these files must be published). The canonical install path inside a consuming repo is .agents/skills/<skill-name>/; every target repo in The Interdependency follows this convention (see ORG_DISTRIBUTION.md). Other paths like .skills/ or .local/skills/ also work as long as your agent harness walks them.

Agents consuming this lib should start at AGENTS.md; a machine-readable index of skills is at skills.json. Root LLM-facing instructions are generated into llms.txt from self-declared LLMS blocks.

What’s inside

Support this work

skill-lib is MPL-2.0 and free to embed. If msdmd or these skills saved you time, effort, or energy, you can route some of it back: Cash App.

The work asks no faith — run the checkers and watch them pass. What support funds is continuation: the checkers stay maintained, the skill families keep growing, and the conventions stay free for the next person who needs them early enough to matter.

Install as a Claude Code plugin marketplace

This repo doubles as a Claude Code plugin marketplace (.claude-plugin/marketplace.json). From any Claude Code session:

/plugin marketplace add The-Interdependency/skill-lib
/plugin install skill-lib@skill-lib

Skills load namespaced (e.g. /skill-lib:msdmd). The vendored-copy install path (.agents/skills/<skill-name>/) remains the canonical convention for org repos; the marketplace route is for direct use and outside adopters.

Install as a Codex plugin

The repository root is a Codex plugin. Its .codex-plugin/plugin.json exposes generated adapters under skills/. Each adapter loads its canonical root */SKILL.md, keeping the existing root skill as the sole doctrine source while making every registered skill installable through Codex.

Canonical SKILL.md frontmatter is the trigger authority. skills.json repeats each description only as a checked index field; the drift gate requires exact agreement, and generated adapters read the canonical frontmatter directly.

During local plugin testing, place this repository behind a Codex local marketplace entry, install skill-lib, then begin a new conversation. The installed plugin exposes every skill in skills.json.

Usage maturity is local and contains no prompt text. Each material skill use loads skill-usage, which records into $PLUGIN_DATA/usage.json:

python "$PLUGIN_ROOT/tools/skill_usage.py" record canon \
  --state "$PLUGIN_DATA/usage.json" \
  --outcome hmmm

python "$PLUGIN_ROOT/tools/skill_usage.py" status \
  --state "$PLUGIN_DATA/usage.json"

Outside an installed plugin, omit --state to use .skill-lib/usage.json. See skill-usage/SKILL.md for the designation thresholds, quality caps, critical-failure handling, and the documented automation boundary.

After changing skills.json or canonical skill metadata, rebuild and check the Codex adapters:

python tools/build_codex_plugin_skills.py --apply
python tools/build_codex_plugin_skills.py --check

VM coding-agent launcher

The canonical ai.sh launcher lives at tools/ai.sh. It runs on Termux, reaches the a0 VM through the SSH host alias a0, and manages the remote a0 tmux session. Install it into the caller PATH without copying the implementation:

bash tools/install_ai.sh

On Termux the installer symlinks ai.sh into $PREFIX/bin; elsewhere it falls back to ~/.local/bin/ai.sh. ai.sh status reports remote pane state, ai.sh restart deepcode repairs a missing/dead DeepCode window, and pane output persists on the VM under ~/.local/state/a0/logs. ai.sh keys only propagates already-present VM login-environment keys into tmux and reports present/missing, never values.

Maintenance tools

Pure-stdlib helper scripts live in tools/. The small llms/ package exists only to provide the python -m llms.build command.

python tools/check_skill_lib_drift.py --warnings-fail
python tools/check_skill_compliance.py --warnings-fail
python tools/char_compress_check.py
python tools/propagate_skills.py ../target-repo          # dry-run
python tools/propagate_skills.py ../target-repo --apply  # copy local files
python -m llms.build --root . --out llms.txt             # dry-run
python -m llms.build --root . --out llms.txt --apply     # write generated file
python -m llms.build --root . --out llms.txt --check     # drift gate

The drift checker compares skill directories, canonical frontmatter, skills.json, README.md, ORG_DISTRIBUTION.md, AGENTS.md, and CLAUDE.md. The skill compliance checker also rejects explicitly superseded vendored skills. The skill compliance checker enforces baseline skill-build invariants and reports softer normalization guidance as warnings. The propagation helper updates canonical files in a checked-out target repo, preserves repo-local additions, and removes retired canonical files only when the target’s cited prior source proves their identity. The char-compress runner executes preservation fixtures for negation, quantifier, order, values, statuses, secrets, hmmm, and unearned theorem/status leakage. The llms-build runner generates the root llms.txt from LLMS blocks and can fail on drift in --check mode.

|∆|Implementation status: this repo ships the universal msdmd parsers, a partial Python per-module metadata reader, skill specifications, selected pure-stdlib helper tools, and the llms-build runner. Most other application skills define runner contracts for consuming repos; they do not ship standalone executors here unless a helper file exists in that skill directory or package.| ∆|

The core idea

Consume declarations where they already live; do not demand a second copy. A docstring can own symbol documentation, a package manifest can own package metadata, and a native ownership file can own review rules. MSDMD preserves source identity and scope while making this information available to shared collection consumers. Supplemental MSDMD blocks express remaining obligations.

Native-first coverage measures required information, not compulsory block adoption. Missing blocks, genuinely missing information, unsupported readers, conflicting declarations, and unverified behavior remain separate findings. The affected application skills and their load-bearing descriptions apply the same native-first coverage rule without removing their semantic obligations.

The universal parsers and msdmd/collect.py remain block readers. The separate msdmd/module_projection.py runner implements a bounded native slice for Python symbols, signatures, decorators, docstrings, and structurally attached comments, using the versioned msdmd/module-projection.schema.json JSONL format. Broader native ingestion and the unified native-capable collection schema remain implementation work. skills.json keeps the shipped collector discoverable as runnable, with runner_scope: msdmd-blocks-only, while native_ingestion is separately marked partial with its exact Python scope. The generic collector still lacks qualified edge identities and duplicate-ID diagnostics; its prototype graph is not an identity validation result. See the helper limitations.

Supplemental block syntax (universal)

# === <BLOCK_NAME> ===
# id: <unique_snake_case_id>
#   <field>: <value>
#   <field>: <value>
#
# id: <next_entry_id>
#   <field>: <value>
# === END <BLOCK_NAME> ===

The comment marker (#, //, --, etc.) is whatever’s idiomatic for the file’s language. The fence text and field structure are identical across languages. See msdmd/SKILL.md for the authoritative spec.

Extending the lib

Skills come in two kinds. Pick the right one for what you’re adding.

Metadata-block skills apply msdmd to a domain’s required information, native owning sources and optional supplemental syntax (doc-build, cap-build, deps-build, owner-build, test-build, meta-module-build, risk-boundary-build, ratios, manifest, llms-build, and typed-meta-frontend are the existing examples). The historical kind label does not make custom blocks compulsory. To add one:

1. Define the required information and its owning scopes; inventory existing native conventions before requesting supplemental declarations.
2. Specify native-reader mappings and support boundaries. Pick a <BLOCK_NAME> only for information that needs an MSDMD-specific declaration.
3. Specify or implement extraction, reconciliation, information-coverage checks, and the executor. Keep the universal parser for the supplemental block path.
4. Author a SKILL.md with usage guidance, reader-status boundaries, and tests.

test-build/ is the canonical worked example. llms-build/ is the worked example for a metadata-block skill that also ships a stdlib command module.

Procedural skills define an agent behaviour without an msdmd block (canon, domain-claims, visitor-intro, char-compress, agent-instantiation, a0p-instancing, plain-lens, thought-lens, gonol-build, ucns-option-selection, epac-selection-display, meta, the-interdependency, interdependent-work-graph, stack-update, project-incubation-graduation, distributed-publication, loop-eng, fresh-making, action-calibration, repo-audit-repair, skill-build, skill-usage, ssh-automation, and vm-mcp are the existing examples). To add one:

1. Define when the skill loads (the description field in the YAML frontmatter is what your harness will read).
2. State the doctrine the skill enforces and the output shape it produces.
3. Author the SKILL.md as a self-contained behavioural spec — no block schema or executor is required.

Whichever kind you add, register it in skills.json and link it from the table above.

Testing

Run the stdlib editorial test suite after changing skills or parser files:

python -m unittest discover -s tests

The suite checks skill/index consistency, skills.json semantics, per-skill spec coverage, SKILL.md frontmatter, README skill links, collection-point schema, generator, visualizer coverage, universal parser behavior, llms-build behavior, and parser ratio bookends.

Versioning and stability

• The msdmd block syntax is treated as a stable contract — breaking changes will go through a major version bump.
• Skill executors and field schemas live in their own SKILL.md files and may evolve independently.
• The universal parsers (msdmd/parsers/universal.{py,ts}) commit to pure-stdlib dependencies; you can copy them anywhere.
• The repo-level collection point shape lives at msdmd/collection.ts; consuming repos can import or copy it for <reponame>_msdmd.ts.
• A stdlib collection generator prototype lives at msdmd/collect.py and can emit <reponame>_msdmd.ts from parsed module-local blocks.
• A stdlib Python native reader lives at msdmd/module_projection.py and emits deterministic per-module .msdmd.jsonl sidecars without executing source.
• A minimal Mermaid visualizer prototype lives at msdmd/visualize.py and can render collection edges and gaps.
• The llms-build runner lives at llms/build.py and can generate or check root llms.txt from LLMS blocks.

Open exact README source