AGENTS.md

This repository is the source of truth for the Lightcone Research agent skills. It is not an application — it packages SKILL.md-based skills for three install targets (the npx skills CLI, the Claude Code plugin marketplace, and Codex plugins) from a single canonical source. Two plugins: astra (spec reference) and lightcone (project companion, which bundles astra). Plugin skills are namespaced by plugin name (e.g. /astra:astra, /lightcone:lightcone).

Where things live

• src/skills/<name>/SKILL.md — the canonical skills. Edit these. One directory per skill; the directory name must equal the name: in the frontmatter.
• src/hooks/<plugin>/ — per-plugin hooks.json + bash scripts (astra/ validates on save and reminds the agent to load the skill).
• skills.config.json — declares how skills compose into the plugins. A plugin composes with others two ways: dependencies (bundled build-time closure) and requires (documented-only prerequisite the user installs — not bundled).
• scripts/build.mjs, scripts/validate.mjs — the generator and the validator.
• tests/<plugin>.yaml — declarative e2e hook-dispatch test specs, run by scripts/e2e-hooks.mjs (npm run e2e, and the e2e-hooks CI workflow) against real headless Claude Code and Codex sessions. To cover a new plugin, add a spec here — no runner changes needed.

Documentation lives in another repo

User-facing documentation is not kept here. It lives in LightconeResearch/docs (the agent-skills pages are under content/docs/agent-skills/) and is published at https://docs.lightconeresearch.org. When a change here adds a skill or plugin, or changes anything else users should know about (install steps, skill behavior, prerequisites, tool pins that change what users run), open a matching PR in that repo.

Generated — do not hand-edit

.claude-plugin/marketplace.json, .agents/plugins/marketplace.json, the entire skills/ and plugins/ trees, and manifest.json are generated from skills.config.json + src/. After changing any skill or the config:

npm run build     # regenerate all target files
npm test          # validate frontmatter + assert nothing drifted

Commit the regenerated files alongside your source change. npm test fails if the generated files are out of sync, if skills/ or plugins/ holds a file the build didn't produce, or if a SKILL.md exists anywhere outside src/skills/ and those two trees. The generator is zero-dependency (Node ≥ 18 built-ins only) — no npm install is required.

Tool pins

Tool pins have one source of truth — each plugin's tools map in skills.config.json (astra-spec is deliberately unpinned and resolves from the astra-tools release). Canonical src/skills/ and src/hooks/ never carry a concrete tool version: they write the literal @x.y.z placeholder, and npm run build substitutes each bundling plugin's pin into the generated plugins/<name>/ copies, and the owning plugin's pin (the first plugin listing the skill in its own skills) into the flat skills/ copy. A plugin's effective pins merge over its dependency closure (own entries win), so a bundling plugin inherits its dependencies' pins unless it overrides them. npm test fails if canonical text carries a concrete version, if a placeholder is left unpinned, or if canonical text pins astra-spec at all. To bump: edit the one number in skills.config.json, run npm run build, commit — no other file changes.

Build tooling — design & rationale

If you arrived expecting a plain skills folder and found a generator, here's why it exists and the shape it takes, so nothing surprises you.

Why a generator at all (not hand-maintained JSON). The three targets disagree on layout. npx skills reads a flat top-level skills/ tree — before any manifest — and its update re-fetches from the folder it installed from. The Claude and Codex (OpenAI Codex CLI) marketplaces instead point every plugin at a self-contained plugins/<name>/ — .claude-plugin/marketplace.json and .agents/plugins/marketplace.json, plus a plugins/<name>/.codex-plugin/plugin.json with its own skills/ directory per plugin — and, for a plugin that ships hooks, its own hooks/ directory too (every harness reads the same hooks.json protocol; hook commands locate the plugin root as ${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT} — CLAUDE_PLUGIN_ROOT is the one root variable every harness defines, the fallback covers older versions — so the generator declares the same hooks file and packages the canonical src/hooks/ tree under the plugin root). And every installed copy needs real tool pins, which the canonical text deliberately lacks. Maintaining all of that against one set of skills by hand is exactly what drifts silently. So skills.config.json + src/ is the single source, and everything per-target — skills/ included — is generated and drift-checked. Do not edit a generated file to fix a target — change the source and rebuild. If a manifest looks wrong, the bug is in skills.config.json or scripts/lib.mjs, not in the output.

How the pieces fit. scripts/lib.mjs is the engine: it loads the config, parses each SKILL.md frontmatter, computes the transitive skill closure per plugin (own + dependencies skills — a plugin's generated dir bundles its whole closure so it installs identically on both harnesses; requires prerequisites are deliberately NOT in the closure), and returns the exact files + byte-copies every target needs. build.mjs writes them; validate.mjs regenerates in memory and diffs against disk. Both import lib.mjs so the generator and the checker agree by construction.

Two deliberate, non-obvious choices (don't change these without reading this):

• Zero dependencies / hand-written frontmatter parser. lib.mjs parses YAML frontmatter itself (inline + folded/literal scalars) instead of pulling in gray-matter, and there's no tsx/vitest. This is intentional: the generator runs with no npm install, so it works in a fresh checkout and in CI without a setup step. If you add a dependency, you give that up. The parser only needs to handle name and description — if a skill ever needs richer frontmatter parsing, that's the tradeoff to weigh.
• Generated plugin contents are real files, not symlinks. A plugin installer archives the plugin directory and does not follow symlinks that point back to canonical src/skills/, src/agents/, or src/hooks/ — this holds for every harness, not just one. The generator therefore copies the complete closure into plugins/<name>/, while canonical files remain the only authoring source. The flat skills/ tree is real files too: the npx skills CLI skips symlinked skill dirs, and its update check needs a git tree, not a link blob, at the installed path. validate.mjs compares every packaged file byte-for-byte with that source and checks executable permissions, so generated copies cannot drift silently.

Prior art. The pattern is borrowed: databricks/databricks-agent-skills (a generated manifest.json registry from skill frontmatter, CI-validated, plus per-agent plugin dirs incl. .codex-plugin/) and supabase/agent-skills (the source: "./" + strict: false Claude marketplace style, and a build + sanity-test workflow). We trimmed both to zero-dep and reconciled them to the three-target need.

Authoring conventions

• name: 1–64 chars, lowercase letters/digits/hyphens, matches the directory.
• description: ≤ 1024 chars; say what it does and when to use it, with trigger keywords (this is what an agent reads to decide whether to load the skill).
• Keep SKILL.md under ~500 lines; push depth into references/ and load it on demand.
• Any skill that shells out to astra must run it through the pinned uvx invocation — write uvx astra-tools@x.y.z literally; the build substitutes each bundling plugin's pin from its tools map in skills.config.json — and open with the Prerequisites preflight: confirm the pinned CLI resolves, point to the uv install docs if uvx is missing, and discover command syntax with --help rather than guessing.

See CONTRIBUTING.md for the full add-a-skill walkthrough.