@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/README.md

@@ -0,0 +1,109 @@
+# Clio Coder Library
+
+The Clio Coder library is the canonical home of shareable packages, contributor entry points, and the generated distribution index.
+
+## Package Kinds
+
+The library organizes shareable packages by kind into dedicated directories:
+
+| Kind | Directory | What an author shares | How it is used |
+| --- | --- | --- | --- |
+| **Skill** | `library/skills/` | A procedure and supporting knowledge for the agent | `/skill <skill-name>` |
+| **Agent** | `library/agents/` | A worker recipe: role, tools, budget, and result contract | `/run <agent-id> <task>` or dispatch |
+| **Prompt** | `library/prompts/` | Reusable task text and parameterized instructions | `/<derived-prompt-name> [arguments]` |
+| **Fleet** | `library/fleets/` | An executable multi-agent coordination recipe | `/fleet run <name>` or preview |
+| **Plugin** | `library/plugins/` | A cohesive bundle of resources released together | Inspect contents, invoke member recipes |
+
+## Browsing and Managing Packages
+
+```bash
+# Discover packages in the catalog
+clio-coder library list
+clio-coder library search <query>
+
+# Install packages
+clio-coder library install skill:<name> --project
+clio-coder library install plugin:materio --project
+
+# Inspect installed packages
+clio-coder library skills --all --json
+
+# Read every discovered recipe with its owner, origin and invocation
+clio-coder library recipes --json
+clio-coder library recipes <query> --kind agent
+```
+
+`library recipes` reads the same bounded, body-free inventory Clio reads through `context(scope="library")`, so the operator and the model agree about which recipes exist, who owns them, where they came from and how each one is actually invoked. Both are reads: installation, removal and activation stay operator actions through `library install` and `/library`, and `/skill <name>` stays the way a skill is activated.
+
+In an interactive session, `/library` opens the recipe browser.
+
+## Using These Packages From Another Agent
+
+The same sources are usable by Claude Code and Codex with no converted copy and no duplicated recipe body.
+
+```bash
+# Claude Code: the repository is a standard marketplace
+claude plugin marketplace add iowarp/clio-coder
+claude plugin install tdd@clio-coder
+
+# Codex: .agents/skills already links the canonical trees, so a session
+# started in a clone sees all 39 skills. For every repository:
+ln -s "$PWD/library/skills" ~/.agents/skills/clio-coder
+ln -s "$PWD/library/plugins/materio/skills" ~/.agents/skills/materio
+```
+
+`.claude-plugin/marketplace.json` is generated by `pnpm run library:pin` from the pinned packages in `registry.yaml` and verified by `pnpm run library:check`. It is never edited by hand.
+
+A package is published there only when a peer host would load a real skill surface from it and nothing it would default-scan into a native component. Agent-, prompt- and fleet-only packages, and packages that keep Clio recipes in a top-level `agents/` directory, stay valid first-class library packages with no peer-host projection; `library:pin` prints which ones and why. See [coding agent interoperability](../docs/guide/interop.md) for what each host actually loads.
+
+## Authoring Templates
+
+Working, valid authoring templates for all five package kinds live in `library/_authoring/templates/`:
+
+- `library/_authoring/templates/skill/`: Single skill package with house metadata, triggers, and evals.
+- `library/_authoring/templates/agent/`: Standalone agent recipe with strict v1 format, custom audience, and `skills: []`.
+- `library/_authoring/templates/prompt/`: Reusable prompt with path-derived invocation and argument placeholders.
+- `library/_authoring/templates/fleet/`: Multi-agent coordination contract with a valid DAG and documented prerequisites.
+- `library/_authoring/templates/plugin/`: Composite bundle demonstrating an agent binding a contained skill, prompts, and assets.
+
+Templates are authoring reference models; they live outside the five catalog kind roots and never enter `library/registry.yaml`.
+
+## Contributing Packages
+
+Every native installable package carries a portable `plugin.json` manifest.
+The optional `extensions["ai.iowarp.clio"]` metadata declares a Clio-specific
+kind, resource paths and components; conventional plugin packages can expose
+`skills/` without it. The key is metadata inside the interoperable manifest,
+and does not name a marketplace service or require a directory. Supported
+foreign plugin manifests enter through the separate reviewed import route.
+
+1. **Choose package kind**: Decide whether your contribution is a single-kind package (`skill`, `agent`, `prompt`, `fleet`) exposing exactly one public recipe, or a composite `plugin` bundle combining multiple resources.
+2. **Copy authoring template**: Copy from `library/_authoring/templates/<kind>/` into your authoring tree.
+3. **Author resources**:
+   - Single-kind packages expose exactly one public resource file under their resource root (`skills`, `agents`, `prompts`, or `fleets`).
+   - Place `README.md` at the package root, outside the resource root, so it is not discovered as a second recipe.
+   - Packages may carry explicitly invoked scripts (e.g. for offline evaluation or verification). Runtime tools and session hooks belong to the separate harness extension lifecycle.
+4. **Validate**:
+   ```bash
+   clio-coder library validate <package-path> --json
+   ```
+   Validates manifest schema, resource payloads, package reference markers, and loader compatibility in a read-only pass.
+5. **Pin and check**:
+   ```bash
+   pnpm run library:pin   # regenerates full-tree pins in library/registry.yaml
+   pnpm run library:check # verifies all package bytes against library/registry.yaml
+   ```
+   For curated skills under `library/skills/`, maintainers also run:
+   ```bash
+   pnpm run skills:pin    # updates normalized skill-body provenance in library/skills/registry.yaml
+   pnpm run skills:check  # verifies skill provenance records
+   ```
+   *Full-tree pins* cover every distributed byte for runtime package integrity; *normalized skill hashes* record advisory provenance for audited instructions.
+6. **Try in isolated project**:
+   ```bash
+   clio-coder library register <package-path> --project
+   clio-coder library install <kind>:<name> --project
+   ```
+7. **Submit a focused fork PR**: Push to your fork and submit a PR against `main`.
+
+Built-in agent recipes and baseline fleets remain product-owned under `src/domains/agents/builtins/` and `src/domains/agents/fleets/`.

package/library/_authoring/templates/agent/README.md

@@ -0,0 +1,28 @@
+# Benchmark Scout Agent Template
+
+This template demonstrates a valid standalone **agent** package for Clio Coder.
+
+## Package Structure
+
+```text
+benchmark-scout/
+  README.md                     # Documentation (outside resource root)
+  plugin.json                   # Portable manifest declaring kind: agent
+  agents/
+    benchmark-scout.md          # Agent recipe (strict v1 format)
+```
+
+> **Important**: Place `README.md` at the package root, never inside the `agents/` resource root. Single-kind packages expose exactly one public candidate in their declared resource directory.
+
+## Recipe Constraints
+
+- Must use version 1 schema (`version: 1`).
+- Standalone agents declare `skills: []` and cannot bind external package skills.
+- Must declare `audience: custom` (only built-in recipes can use other audiences).
+- Valid budget, tools (required and optional), capability class, category, and result contract.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

package/library/_authoring/templates/agent/agents/benchmark-scout.md

@@ -0,0 +1,30 @@
+---
+version: 1
+name: Benchmark Scout
+description: Inspect computational benchmarks, scaling configurations, and performance harnesses in research codebases.
+tools:
+  required: [read, context]
+  optional: [grep, find, ls]
+skills: []
+audience: custom
+category: science
+capabilityClass: read-only
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 32, readReserve: 4, synthesis: true}
+resultContract: {kind: scout-report}
+tags: [benchmarks, hpc, performance, science]
+---
+
+# Benchmark Scout
+
+You are Benchmark Scout, a read-only specialist for discovering, analyzing, and characterizing performance benchmarks in scientific computing and research software.
+
+## Mission
+Inspect benchmark harnesses, scaling runs (strong and weak scaling), and measurement scripts without modifying the workspace or executing unverified code.
+
+## Procedure
+1. **Discover harnesses**: Locate benchmark definitions, Slurm job scripts, MPI run configurations, and test inputs.
+2. **Analyze configurations**: Check problem sizes, grid resolutions, thread pinning, and environment variables.
+3. **Document baselines**: Summarize reported metrics (throughput, memory bandwidth, latency, speedup).
+4. **Deliver scout report**: Return structured findings under the scout-report contract.

package/library/_authoring/templates/agent/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "benchmark-scout",
+	"version": "1.0.0",
+	"description": "Inspect computational benchmarks, scaling configurations, and performance harnesses.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "agent",
+			"resources": {
+				"agents": "agents"
+			},
+			"components": [
+				{
+					"kind": "agent",
+					"id": "benchmark-scout",
+					"path": "agents/benchmark-scout.md"
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/fleet/README.md

@@ -0,0 +1,29 @@
+# Pipeline Review Fleet Template
+
+This template demonstrates a valid standalone **fleet** package for Clio Coder.
+
+## Package Structure
+
+```text
+pipeline-review/
+  README.md                     # Documentation (outside resource root)
+  plugin.json                   # Portable manifest declaring kind: fleet
+  fleets/
+    pipeline-review.md          # Multi-agent coordination contract
+```
+
+> **Important**: Place `README.md` at the package root, never inside the `fleets/` resource root. Single-kind packages expose exactly one public candidate in their declared resource directory.
+
+## Graph and Step Semantics
+
+- **Version**: Version 1 or higher (v4 introduces strict write boundaries).
+- **Steps**: Each step specifies `id`, `agent`, `scope`, and `dependencies`.
+- **Graph Validity**: Steps must form a directed acyclic graph (DAG) without cycles or unknown dependencies.
+- **Prompt Body**: Uses strict `{{var}}` interpolation; all variables must be supplied at invocation (e.g. `--var pipeline=configs/pipeline.yaml`).
+- **Prerequisites**: Fleets that reference core built-in agents (e.g., `scout`, `verifier`) should clearly document these dependencies in their body.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

package/library/_authoring/templates/fleet/fleets/pipeline-review.md

@@ -0,0 +1,31 @@
+---
+version: 1
+name: pipeline-review
+description: Coordinate a two-stage inspection of scientific pipeline data definitions and validation assertions.
+steps:
+  - id: inspect-pipeline
+    agent: scout
+    scope: readonly
+    dependencies: []
+  - id: verify-invariants
+    agent: verifier
+    scope: readonly
+    dependencies: [inspect-pipeline]
+maxWorkers: 2
+onFailure: stop
+---
+
+Review the scientific pipeline specified at: {{pipeline}}.
+
+## Workflow Stages
+
+1. **inspect-pipeline (`scout`)**:
+   Inspect data schemas, pipeline steps, dependency declarations, and configuration inputs in the target pipeline.
+2. **verify-invariants (`verifier`)**:
+   Independently verify that numerical tolerances, sanity checks, regression tests, and invariant assertions are defined and bounded.
+
+## Prerequisites & Environment Requirements
+
+- **Core Agents**: This fleet coordinates the built-in `scout` and `verifier` recipes provided by Clio (`src/domains/agents/builtins/`).
+- **Configuration**: Requires a configured read-only model target with context support.
+- **Variables**: The caller must supply the `{{pipeline}}` variable naming the pipeline configuration or script path (e.g. `--var pipeline=configs/pipeline.yaml`).

package/library/_authoring/templates/fleet/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "pipeline-review",
+	"version": "1.0.0",
+	"description": "Multi-agent coordination recipe for reviewing scientific data pipelines.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "fleet",
+			"resources": {
+				"fleets": "fleets"
+			},
+			"components": [
+				{
+					"kind": "fleet",
+					"id": "pipeline-review",
+					"path": "fleets/pipeline-review.md"
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/plugin/README.md

@@ -0,0 +1,37 @@
+# Data Curation Plugin Template
+
+This template demonstrates a valid composite **plugin** bundle for Clio Coder.
+
+## Package Structure
+
+```text
+data-curation/
+  README.md                                 # Documentation
+  plugin.json                               # Manifest declaring bundle resources & components
+  assets/
+    curation-guide.md                       # Supporting reference asset (component:resource:guidelines)
+  skills/
+    dataset-curation/
+      SKILL.md                              # Bound skill
+      evals.md                              # Skill evaluation scenarios
+  agents/
+    data-curator.md                         # Agent binding dataset-curation skill
+  prompts/
+    inspect-dataset.md                      # Prompt requiring data-curator agent
+```
+
+## Manifest Declarations
+
+- **Resources**: Declares ordinary `skills`, `agents`, and `prompts` directories under `extensions["ai.iowarp.clio"]`.
+- **Components**:
+  - `resource:guidelines` -> `assets/curation-guide.md`
+  - `skill:dataset-curation` -> `skills/dataset-curation/SKILL.md` (requires `resource:guidelines`)
+  - `agent:data-curator` -> `agents/data-curator.md` (requires `skill:dataset-curation`)
+  - `prompt:inspect-dataset` -> `prompts/inspect-dataset.md` (requires `agent:data-curator`)
+- **Acyclic References**: Component dependencies form a clean DAG.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

package/library/_authoring/templates/plugin/agents/data-curator.md

@@ -0,0 +1,31 @@
+---
+version: 1
+name: Data Curator
+description: Inspect and curate scientific datasets against FAIR data guidelines and metadata schemas.
+tools:
+  required: [read, context]
+  optional: [grep, find, ls]
+skills: [dataset-curation]
+audience: custom
+category: science
+capabilityClass: read-only
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 32, readReserve: 4, synthesis: true}
+resultContract: {kind: scout-report}
+tags: [data, fair, curation, science]
+---
+
+# Data Curator
+
+You are Data Curator, a read-only specialist for reviewing scientific datasets and confirming compliance with FAIR principles.
+
+Use the bound `dataset-curation` skill to inspect dataset organization, and check the curation reference at ${component:resource:guidelines}.
+
+## Mission
+Inspect dataset layout, format standards (NetCDF, HDF5, CSV, Parquet), metadata schemas, and licensing documentation.
+
+## Procedure
+1. Check for standard dataset metadata descriptors (e.g. README.md, datapackage.json, or CF conventions).
+2. Validate column definitions, units, and missing value encodings against ${component:resource:guidelines}.
+3. Return findings conforming to the scout-report contract.

package/library/_authoring/templates/plugin/assets/curation-guide.md

@@ -0,0 +1,22 @@
+# Dataset Curation Guide
+
+Guidelines for curating and validating scientific research datasets.
+
+## FAIR Principles Checklist
+
+1. **Findable**:
+   - Unique persistent identifier or stable local path.
+   - Comprehensive metadata descriptor (e.g. `datapackage.json` or `README.md`).
+2. **Accessible**:
+   - Clear retrieval instructions and standard open file formats (CSV, Parquet, NetCDF, HDF5, JSON).
+3. **Interoperable**:
+   - Documented vocabulary, standard units (SI), and recognized domain conventions (e.g., Climate and Forecast CF conventions).
+4. **Reusable**:
+   - Explicit license specification (e.g., CC-BY-4.0, CC0, Apache-2.0).
+   - Data provenance and generation parameters recorded.
+
+## Quality Invariants
+
+- No unencoded NaN or infinite values without documented sentinel symbols.
+- Timestamp formats follow ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
+- Geospatial coordinates follow WGS84 with explicit latitude/longitude bounds.

package/library/_authoring/templates/plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "data-curation",
+	"version": "1.0.0",
+	"description": "Scientific dataset curation bundle with curation skill, curator agent, and inspection prompt.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"resources": {
+				"skills": "skills",
+				"agents": "agents",
+				"prompts": "prompts"
+			},
+			"components": [
+				{
+					"kind": "resource",
+					"id": "guidelines",
+					"path": "assets/curation-guide.md"
+				},
+				{
+					"kind": "skill",
+					"id": "dataset-curation",
+					"path": "skills/dataset-curation/SKILL.md",
+					"requires": ["resource:guidelines"]
+				},
+				{
+					"kind": "agent",
+					"id": "data-curator",
+					"path": "agents/data-curator.md",
+					"requires": ["skill:dataset-curation"]
+				},
+				{
+					"kind": "prompt",
+					"id": "inspect-dataset",
+					"path": "prompts/inspect-dataset.md",
+					"requires": ["agent:data-curator"]
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/plugin/prompts/inspect-dataset.md

@@ -0,0 +1,15 @@
+---
+description: Prompt to inspect a scientific dataset directory for FAIR compliance and metadata completeness.
+argument-hint: "[dataset-path]"
+---
+
+Inspect the scientific dataset at: $1
+
+Refer to curation guidelines in ${pluginRoot}/assets/curation-guide.md and use the data-curator agent.
+
+Evaluate:
+1. File structure and format consistency.
+2. Presence of required metadata, license, and provenance documentation.
+3. Missing-value encodings and schema clarity.
+
+Additional instructions: $ARGUMENTS

package/library/_authoring/templates/plugin/skills/dataset-curation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: dataset-curation
+description: Guidelines and verification procedures for scientific dataset curation, schema compliance, and FAIR data standards.
+version: 1.0.0
+license: Apache-2.0
+clio-coder:
+  registry-id: dataset-curation
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/_authoring/templates/plugin
+  provenance: designed
+  eval-status: scenarios-recorded
+triggers:
+  - curate dataset
+  - fair data check
+  - validate dataset schema
+  - dataset curation
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+---
+
+# Dataset Curation Skill
+
+Guide for inspecting, curating, and validating scientific datasets against FAIR data standards.
+
+## Reference Guidelines
+
+Consult ${pluginRoot}/assets/curation-guide.md for domain quality invariants and metadata checklists.
+
+## Procedure
+
+1. **Scan Dataset Directory**: Use `ls` and `find` to map all data files and metadata descriptors.
+2. **Review Metadata**: Verify existence of licensing, provenance records, and format declarations.
+3. **Inspect Content**: Verify column names, missing-value sentinels, and unit definitions against the curation guidelines.
+4. **Compile Assessment**: Report missing fields, format violations, and recommendations for FAIR compliance.

package/library/_authoring/templates/plugin/skills/dataset-curation/evals.md

@@ -0,0 +1,17 @@
+# Evals: dataset-curation
+
+Evaluation scenarios for dataset curation skill.
+
+## Scenario: missing-fair-metadata
+
+### Baseline (without skill)
+- Context: Dataset folder containing `data.csv` with no license or column description.
+- Task: Check dataset for publication readiness.
+- Outcome: General observations, omits structured FAIR criteria.
+
+### Treatment (with skill)
+- Prompt: `/skill dataset-curation Check dataset at data/ for FAIR compliance`
+- Expected Evidence:
+  - References FAIR criteria from `assets/curation-guide.md`.
+  - Flags absence of license and schema documentation.
+  - Identifies missing unit definitions in CSV headers.

package/library/_authoring/templates/prompt/README.md

@@ -0,0 +1,28 @@
+# Paper Summary Prompt Template
+
+This template demonstrates a valid standalone **prompt** package for Clio Coder.
+
+## Package Structure
+
+```text
+paper-summary/
+  README.md                     # Documentation (outside resource root)
+  plugin.json                   # Portable manifest declaring kind: prompt
+  prompts/
+    paper-summary.md            # Reusable prompt template
+```
+
+> **Important**: Keep `README.md` at the package root, never inside `prompts/`. Single-kind packages expose exactly one public candidate in their declared resource directory.
+
+## Invocation and Parameters
+
+- **Invocation Name**: Derived from the file path relative to `prompts/`. Here, `prompts/paper-summary.md` exposes `/paper-summary`.
+- **Positional Arguments**: `$1`, `$2`, etc. are replaced by space-separated positional arguments passed to the slash command.
+- **Full Arguments String**: `$ARGUMENTS` expands to the full remainder argument string.
+- **Optional Argument Hint**: The frontmatter `argument-hint: "[paper-path-or-url]"` informs interactive autocomplete of expected inputs.
+
+## Validation
+
+```bash
+clio-coder library validate .
+```

package/library/_authoring/templates/prompt/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "paper-summary",
+	"version": "1.0.0",
+	"description": "Structured prompt template for summarizing scientific papers and research methodologies.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "prompt",
+			"resources": {
+				"prompts": "prompts"
+			},
+			"components": [
+				{
+					"kind": "prompt",
+					"id": "paper-summary",
+					"path": "prompts/paper-summary.md"
+				}
+			]
+		}
+	}
+}

package/library/_authoring/templates/prompt/prompts/paper-summary.md

@@ -0,0 +1,26 @@
+---
+description: Summarize a scientific paper with research question, methodology, key findings, and threats to validity.
+argument-hint: "[paper-path-or-url]"
+---
+
+Summarize the scientific paper located at: $1
+
+Follow this structured format:
+
+## 1. Research Problem & Objective
+- What specific research question does this work address?
+- Why is this problem significant in scientific or computational practice?
+
+## 2. Methodology & Approach
+- What experimental, computational, or theoretical methodology was employed?
+- What datasets, benchmarks, or HPC hardware environments were evaluated?
+
+## 3. Key Findings & Contributions
+- Summarize the primary quantitative and qualitative results.
+- Highlight measured speedups, accuracy improvements, or scaling limits.
+
+## 4. Threats to Validity & Limitations
+- What are the documented or observed limitations?
+- What replication obstacles exist?
+
+Additional instructions: $ARGUMENTS

package/library/_authoring/templates/skill/README.md

@@ -0,0 +1,24 @@
+# Citation Check Skill Template
+
+This template demonstrates a valid standalone **skill** package for Clio Coder.
+
+## Package Structure
+
+```text
+citation-check/
+  README.md         # Documentation (outside resource root)
+  plugin.json       # Portable manifest declaring kind: skill
+  SKILL.md          # Skill instructions and metadata
+  evals.md          # Evaluation scenarios
+```
+
+## How to Use This Template
+
+1. Copy this directory into your project or repository.
+2. Rename the package in `plugin.json` and `SKILL.md`.
+3. Update the description, triggers, and procedure in `SKILL.md`.
+4. Add baseline/treatment scenarios in `evals.md`.
+5. Validate your package:
+   ```bash
+   clio-coder library validate .
+   ```

package/library/_authoring/templates/skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: citation-check
+description: Verify citation keys, DOIs, and bibliography entries against source files in research software. Load when checking academic references, bibtex formatting, or paper citations.
+version: 1.0.0
+license: Apache-2.0
+clio-coder:
+  registry-id: citation-check
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/_authoring/templates/skill
+  provenance: designed
+  eval-status: scenarios-recorded
+triggers:
+  - citation check
+  - verify citations
+  - check bibliography
+  - validate doi
+allowed-tools:
+  - read
+  - grep
+  - find
+---
+
+# Citation Check
+
+Verify citation keys, Digital Object Identifiers (DOIs), and bibliography entries in research codebases and papers.
+
+## When to load this skill
+
+Load when:
+- Reviewing LaTeX documents, markdown papers, or documentation containing citation keys (e.g. `\cite{...}`, `[@key]`).
+- Validating BibTeX `.bib` files for syntax errors, missing fields, or duplicate keys.
+- Checking that cited DOIs resolve to expected formats.
+
+## Procedure
+
+1. **Locate citation files**: Search for `.bib` files and references in the workspace using `find`.
+2. **Inspect citation keys**: Grep for citation markers in manuscript or documentation source files.
+3. **Cross-reference**: Ensure every cited key exists in the corresponding `.bib` file. Report unreferenced bibliography entries as warnings and missing keys as errors.
+4. **DOI Verification**: Verify DOIs match the standard format `10.XXXX/...` and link to valid literature sources.
+5. **Report findings**: Output a structured summary containing verified keys, missing citations, and formatting issues.

package/library/_authoring/templates/skill/evals.md

@@ -0,0 +1,30 @@
+# Evals: citation-check
+
+Scenarios recorded for the citation-check skill.
+
+## Scenario: missing-citation-key
+
+### Baseline (without skill)
+- Context: Workspace with `paper.tex` citing `\cite{smith2024}` and `references.bib` containing only `doe2023`.
+- Task: Verify citations in `paper.tex`.
+- Outcome: General unstructured commentary, potential hallucination of reference existence.
+
+### Treatment (with skill)
+- Prompt: `/skill citation-check Check citations in paper.tex against references.bib`
+- Expected Evidence:
+  - Identifies missing citation key `smith2024` in `references.bib`.
+  - Reports `doe2023` as an unreferenced entry.
+  - Leaves workspace files unmodified.
+
+## Scenario: doi-format-validation
+
+### Baseline (without skill)
+- Context: `references.bib` with invalid DOI string `doi = {https://dx.doi.org/invalid}`.
+- Task: Validate DOI formatting in `references.bib`.
+- Outcome: Misses malformed DOI format or accepts invalid prefix.
+
+### Treatment (with skill)
+- Prompt: `/skill citation-check Validate DOI formats in references.bib`
+- Expected Evidence:
+  - Flags invalid DOI prefix.
+  - Recommends canonical DOI format `10.XXXX/...`.