Skills¶

Skills are bundled in the shared lightcone-cli agent bundle. Claude Code and Codex expose them through the plugin manifests; Pi installs the same bundle as a local package and aliases the top-level /lc-* entry points through its extension. They give the agent a structured, phase-by-phase workflow for the most common research operations.

If you're a researcher trying to use these, the Agent Workflow page in the user guide is the friendly version. This page is for maintainers.

Available skills¶

The /lc-from-* family is parallel by what you start from: a question, code, or a paper. /lc-from-paper is the entry point of a six-skill paper-reproduction bundle; the five bundle siblings stand alone and are user-invokable directly.

Project lifecycle¶

Paper-reproduction bundle (sibling skills)¶

Co-located with lc-from-paper so a single lc init brings the full toolkit. Each stands alone and is user-invokable; lc-from-paper dispatches them by role during the reproduction.

See the bundle README for the rationale behind co-location vs plugin install.

Reference skills (auto-primed via session-start)¶

Not direct entry points — invoked by other skills (or by Claude directly when relevant) to load reference content into the working session. The session-start hook names both in its primer, so Claude is aware they exist from the first turn.

These intentionally don't appear in the top-level README — researchers use the project-lifecycle skills directly; the reference skills are infrastructure.

How a skill is wired¶

Each skill is a claude/lightcone/skills/<name>/SKILL.md file with YAML frontmatter:

---
name: lc-new
description: >
  Scope a new ASTRA analysis from a research question...
allowed-tools: Read, Write(astra.yaml), Edit(astra.yaml), Glob, Grep, Bash(astra:*), ...
argument-hint: "[DESCRIPTION]"
---

The frontmatter configures Claude Code: which tools the skill may invoke, and what the slash command's argument hint looks like. The body is the prompt — phase definitions, rules, references to guide files, anti-patterns. The skill bundles its own helper scripts under scripts/ and its loop prompt template under assets/ when relevant.

Plugin layout¶

.claude-plugin/marketplace.json         # marketplace manifest at repo root

claude/lightcone/                        # shared agent-bundle root
├── .claude-plugin/plugin.json           # Claude plugin manifest
├── .codex-plugin/plugin.json            # Codex plugin manifest
├── package.json                         # Pi package manifest (skills + extension)
├── extensions/lightcone.ts              # Pi extension (hooks + /lc-* aliases)
├── skills/
│   ├── lc-new/{SKILL.md, references/*.md}
│   ├── lc-from-code/SKILL.md
│   ├── lc-from-paper/{SKILL.md, references/*.md, templates/{constitution.md, CLAUDE.md}}
│   ├── lc-feedback/SKILL.md
│   ├── ralph/{SKILL.md, references/*.md, scripts/ralph}
│   ├── paper-extraction/{SKILL.md, scripts/*.py}
│   ├── narrative/{SKILL.md, references/*.md}
│   ├── figure-comparison/{SKILL.md, scripts/*.py}
│   ├── check-sentence-by-sentence/SKILL.md
│   ├── astra/SKILL.md                  # reference: astra.yaml spec
│   └── lc-cli/SKILL.md                 # reference: lc workflow
├── agents/lc-extractor.md              # literature subagent for /lc-new
├── hooks/hooks.json                    # hook config (SessionStart, PostToolUse)
├── scripts/*.sh                        # hook handlers (venv, validate-on-save, session-start primer)
└── templates/CLAUDE.md                 # the project CLAUDE.md template

Both .claude-plugin/marketplace.json and claude/lightcone/ are force-included into the wheel via pyproject.toml::tool.hatch.build.targets.wheel.force-include, so lc init can run claude plugin marketplace add, codex plugin marketplace add, or pi install against the wheel's install directory whether you're working from source or PyPI.

Other plugin files¶

The two reference skills (/astra and /lc-cli) live under skills/ and are listed in the Reference skills section above. Remaining plugin files:

Authoring a new skill¶

See Authoring Skills.