plugin-template

The scaffold for a new Open Science Pillars capability: copy it, rename it, replace the examples, and the gate runs on your first pull request. The walkthrough with measured timings is Tutorial 3, Build a Domain Plugin in the tutorials repository (12.3 minutes scaffold-to-installed); what every file under .osp/ means, and how a dependency, a connector or a qualification requirement is declared, is the marketplace repository's package authoring guide. The words used on this page (capability, plugin, package, sphere, knowledge bundle, runtime) are defined in the glossary.

From copy to gated

1. Copy the repository. Create the new repository from this one (a template copy or a clone with the history dropped) in a workspace that also holds a checkout of build-kit and nasa-daac-knowledge beside it, the way the gate lays them out.
2. Rename. Set repository.name in .osp/repository.yaml (a copy fails osp.py validate until it is no longer plugin-template) and, for a domain capability, set kind to capability there with its sphere and discipline; set the package name, description and keywords in .osp/package.yaml; rename the release tag pattern in .github/workflows/plugin-gate.yml to <plugin-name>--v*; and put the plugin's name at the top of CONNECTORS.md.
3. Delete the examples once you have real ones. The example computation is one unit in three places: the skill with its two scripts (skills/example-workflow/), the concept that declares the contract and the data root the executor reads (knowledge/computations/example-workflow.md and knowledge/references/retrieval/example-series/), and the golden that proves the scripts (verification/example_workflow.py). Delete them together or replace them together; a concept whose executor is gone fails the gate. Also delete the two example agents (agents/example-scout/, agents/example-reviewer/). The rest of the knowledge bundle starts empty (concepts of the other types come from knowledge-template) and evals/ holds only the pointer to the case schema; the first high-severity gotcha you write brings the first eval case with it.
4. Validate and render. From the repository root: uv run ../build-kit/scripts/osp.py validate . && uv run ../build-kit/scripts/osp.py render . The second command writes the Claude manifest and .mcp.json and the Agent Plugins plugin.json and mcp.json from .osp/package.yaml; never edit those four by hand, the gate fails on a hand edit.
5. Open the first pull request. .github/workflows/plugin-gate.yml runs on every pull request and on main: the manifest validates (claude plugin validate), the canonical metadata validates and the projections are current (osp.py validate, osp.py render --check), the portable package conforms to Agent Plugins 1.0.0 (osp.py plugin-check), the README's runtime table is current and no runtime is advertised without a qualified record (osp.py advertise --check), the release lock is reported, the bundle conforms to OKF v0.2 (check_okf_v02.py), every script's PEP 723 header covers what it imports (check_script_deps.py), the wording rules hold (check_prose.py: specification rules cited by name, no program bookkeeping, no em or en dashes) and the signature debt is reported (signature_check.py); a release tag enforces the lock and zero debt. osp.py validate is also what holds the placement of files: runnable code under knowledge/ is an error, and a computation concept's executor and attester must resolve inside the package and be named by a golden. .github/workflows/goldens.yml runs every golden notebook at the top of verification/ headless on what is committed. .github/workflows/release-qualification.yml treats a pull request that changes the package version, or carries the release label, as a release candidate: one ticket opens per required runtime and the merge waits on a qualification record or a waiver for each (the marketplace repository's release qualification guide).

Layout

your-plugin/
├── .claude-plugin/plugin.json    # the Claude projection, rendered from .osp/package.yaml
├── .mcp.json                     # the Claude connector wire, rendered likewise (when reach is declared)
├── plugin.json · mcp.json        # the Agent Plugins 1.0.0 projection, rendered likewise
├── .osp/                         # canonical metadata (the package authoring guide):
│   ├── repository.yaml           #   kind, status, spheres, discipline
│   ├── package.yaml              #   name, version, dependencies, metadata, reach
│   ├── release-lock.json         #   digests of one release, written by osp.py lock
│   ├── surfaces.yaml             #   runtime support policy and the qualification a release needs
│   └── governance.yaml           #   maintainers, runtime maintainers, review policy
├── .github/workflows/
│   ├── plugin-gate.yml           # the merge gate, as CI; rename the tag pattern
│   ├── goldens.yml               # every golden notebook, headless, on the committed fixtures
│   └── release-qualification.yml # tickets per required runtime on a release candidate
├── README.md · LICENSE · CITATION.cff
├── CONNECTORS.md                 # network disclosure; shared text plus the per-plugin table
├── skills/                       # what an agent runs, with its scripts beside it
│   └── example-workflow/         # annotated example computation; replace it
│       ├── SKILL.md              #   the run procedure: bind a value, attest, quote
│       └── scripts/              #   invoked through ${CLAUDE_PLUGIN_ROOT}, never a relative path
│           ├── example_executor.py  # binds the parameter, writes the receipt, refuses out of range
│           └── example_attester.py  # rechecks a receipt with no language model in the path
├── agents/                       # subagents, one directory each
│   ├── example-scout/agent.md    # read-only planner skeleton; replace it
│   └── example-reviewer/agent.md # propose-never-modify auditor skeleton; replace it
├── knowledge/                    # what a steward signs: knowledge and evidence, no runnable code
│   ├── index.md · log.md         #   every concept listed; change history
│   ├── computations/             #   one Attested Computation concept per computation
│   │   └── example-workflow.md   #   names the executor, the receipt fields and the attester
│   └── references/retrieval/     #   the data a computation reads, stamped, as data
│       └── example-series/       #   example_series.csv and its SOURCES.json provenance stamp
├── verification/                 # what proves a script; nothing here is run by a skill
│   └── example_workflow.py       # the golden: executor, attester, refusal; the pattern to copy
└── evals/                        # eval cases, added with your gotchas
    ├── README.md                 # what lives here and where the format is defined
    └── SCHEMA.md                 # pointer to the case schema's one home

The example ships no verification/fixtures/, because the data its executor reads is the bundle's data root and the golden reads the same root. A golden that needs a frozen input of its own keeps it under verification/fixtures/ and records its source, version and license in a README there (the fixture-provenance rule).

The rules that gate a merge

1. Every SKILL.md starts with frontmatter: name; description 200 characters or fewer, keyword-first (verify the loaded budget with the skills panel on Claude Code). Knowledge skills set user-invocable: false; workflow skills never set disable-model-invocation: true (it would kill conversational runtimes).
2. Side effects (downloads, file writes) are guarded by in-skill confirmation gates, in the skill body, so they work on every runtime.
3. A skill that runs a computation is not done until its golden in verification/ runs green headless (uv run verification/your_workflow.py, nonzero exit on failure; the PEP 723 header at the top of the file is what makes that resolve on any machine). The golden reads only what is committed, names the skill's scripts and runs them; the goldens workflow runs every golden at the top of verification/.
4. Where files go is one sentence: what a steward signs is under knowledge/, what an agent runs is under skills/<name>/ with its scripts beside it, what proves a script is under verification/, and what reaches a service is under connectors/. Three consequences the gate measures: nothing under knowledge/ is runnable, a script a skill runs is invoked through ${CLAUDE_PLUGIN_ROOT} and never by a path relative to the working directory, and the direction between a skill and its golden is one way, a golden names a skill's scripts and no skill names anything under verification/.
5. Knowledge bundles conform to the specification's knowledge-layer rules (docs/SPECIFICATION.md in open-science-pillars/marketplace): knowledge and evidence, no runnable code. Start from knowledge-template, which carries an annotated example of the concept types a bundle holds.
6. Every high-severity gotcha ships a matching eval case in evals/; the case format is the marketplace repository's docs/testing.md.

The computation this template ships

A computation is a skill. The example is the shape to copy: a concept, two scripts and a golden, in three places.

• The concept, knowledge/computations/example-workflow.md, an Attested Computation in OKF v0.2 shape: the runtime, the one parameter a caller may bind and its range, the path of the executor, the fields a receipt carries, the path of the attester, its sources and status: draft until a steward signs it. Its computation and attester.resource are paths relative to the concept and resolve to the scripts in the skill beside it.
• The executor, skills/example-workflow/scripts/example_executor.py, which binds the declared parameter, reads the data root, and writes a receipt with a run identifier, the digest of its own file, the bound parameters and the results. A value outside the declared range is refused with a reason code and exit status 3, and writes no receipt.
• The attester, skills/example-workflow/scripts/example_attester.py, which takes a receipt and returns a verdict with no language model in the path: it hashes the executor, regenerates the data the executor read and recomputes every number in the receipt, and exits nonzero on any drift.
• The golden, verification/example_workflow.py, which runs the executor on the committed data root, the attester on the receipt it wrote, the refusal on a value out of range, and the attester once more on a receipt with one number changed, which must fail.

The SKILL.md is the run procedure: bind values only, pass the name of the runtime, run the attester before quoting a number, and cite the concept by path. The data the executor reads is data, so it lives in the bundle under knowledge/references/retrieval/ with a SOURCES.json stamp, not beside the code. A capability may group several computations into one skill when one workflow runs them together; the concepts stay one per computation.

The sections below are the README your capability ships. Keep their order (it is the one every capability in the organization uses), replace every <placeholder>, and leave the runtime table to the tool that renders it.

<One paragraph for a scientist, in plain words: what you can do with this capability, with no organization vocabulary before a concrete sentence.> It is a capability, discipline (kind: capability in .osp/repository.yaml); the words used on this page (capability, plugin, sphere, knowledge bundle, runtime) are defined in the glossary.

Install

On Claude Code:

claude plugin marketplace add open-science-pillars/marketplace
claude plugin install <plugin-name>@open-science-pillars

What comes with it: core <and any knowledge dependency, by name>, declared as dependencies, so the one install brings them with it. An install stays at the release it was installed from: claude plugin update <plugin-name>@open-science-pillars moves this plugin and only this plugin; a dependency moves by its own update command, and a release that raises a floor says so in its notes. claude plugin list shows what you have.

On Claude Cowork: add the marketplace by repository (open-science-pillars/marketplace) under Customize > Plugins > Add marketplace, then install the same capability from it; the shell commands on this page are for Claude Code.

Local requirements: uv. Every script here declares its dependencies in a PEP 723 header and runs as uv run <script>; never python script.py. <Which credential retrieval needs (an Earthdata Login, a service key), which archives need a further authorization on the account, and that searching needs none.>

Runtimes

Which runtimes this release is qualified on is the table below, rendered from the qualification records; what each word asserts is in the marketplace repository's docs/runtime-distribution.md.

Runtime support for your-plugin-name 0.1.0 (release lock sha256:d579855e2d22), rendered by build-kit's osp.py advertise from .osp/surfaces.yaml and the qualification records; edit those, not this block.

Runtime	Role	Declared status	Qualification
Claude Code	development and runtime, required	supported	Supported (development environment)
Claude Cowork	runtime, required	planned	Not qualified
OpenAI Codex	runtime, required	planned	Not qualified
Claude Science	future runtime	limited-release	Outside the required matrix

A runtime is advertised as supported only on a qualified record for this exact release; a release stays valid when a runtime is not qualified, and that runtime is simply not advertised.

First result

What's inside

• Skills (skills/, one SKILL.md each, the scripts it runs in its scripts/): <names, two or three lines>.
• Agents (agents/): .
• Knowledge (knowledge/): <what the local bundle holds, the computations it declares under computations/, and the provider bundle it depends on, by repository and bundle path>.
• Verification (verification/): <the goldens by name, and which script each proves>.
• Evals (evals/): <the cases, or the repository that is their home>.

Configuration

<The <plugin-name>.local.md.template file, where to copy it, what it controls; omit the section if the capability has no local file.>

Connectors and credentials

The disclosure is CONNECTORS.md.

Contributing

Start with the marketplace repository's CONTRIBUTING.md and the guides under its docs/ (contributing a skill, contributing knowledge, testing, the package authoring guide).

License and citation

Apache-2.0. Cite via CITATION.cff.