---
name: Reference-First Template
slug: reference-first-template
category: AI Engineering
description: "Reference-First Template provides a reusable shape for skills built around a lean router, reference files, machine-readable assets, and a deterministic script. Use it when creating or refactoring a skill into this repository's reference-first structure."
github: "https://github.com/WILLOSCAR/research-units-pipeline-skills/tree/main/.codex/skills/_template_reference_first"
language: Python
stars: 499
forks: 39
install: "npx degit https://github.com/WILLOSCAR/research-units-pipeline-skills/tree/main/.codex/skills/_template_reference_first ~/.claude/skills/_template_reference_first"
installs_to: ~/.claude/skills/_template_reference_first
source_path: .codex/skills/_template_reference_first/SKILL.md
collection_size: 25
category_size: 2451
collection_url: "https://dirskills.com/collections/WILLOSCAR/research-units-pipeline-skills"
added: 2026-08-26T05:12:50.046Z
last_synced: 2026-08-26T05:12:50.046Z
canonical_url: "https://dirskills.com/skills/reference-first-template"
---

# Reference-First Template

Reference-First Template provides a reusable shape for skills built around a lean router, reference files, machine-readable assets, and a deterministic script. Use it when creating or refactoring a skill into this repository's reference-first structure.

**Install:**

```bash
npx degit https://github.com/WILLOSCAR/research-units-pipeline-skills/tree/main/.codex/skills/_template_reference_first ~/.claude/skills/_template_reference_first
```

## README

# Reference-First Skill Template

## Why this exists

This package is the default starting point for new or refactored skills in this repo.

It demonstrates the intended split of responsibilities:
- `SKILL.md` routes the workflow
- `references/` holds method, judgment, and exemplars
- `assets/` holds machine-readable contracts
- `scripts/` handles deterministic execution only

Use it as a shape to copy and customize, not as a domain-specific skill.

## Inputs

- the job the skill should encode
- the expected inputs and outputs for that job
- acceptance criteria and failure conditions
- any domain packs, schemas, or existing artifacts that must be reused

## Outputs

- a lean `SKILL.md`
- `references/overview.md`
- `references/examples_good.md`
- `references/examples_bad.md`
- `assets/schema.json`
- `scripts/run.py`

## Workflow

1. Define the job and its boundary
- write down the trigger, intended outcome, and explicit non-goals
- separate reusable behavior from one-off project context

2. Write `SKILL.md` as a router
- keep only the activation rule, inputs, outputs, workflow, block conditions, and resource routing
- do not copy large judgment rules, domain essays, or sentence banks into this file

3. Move reusable thinking into `references/`
- put domain knowledge, decision rubrics, and method notes in `references/overview.md`
- if the skill can emit reader-facing text, include both `references/examples_good.md` and `references/examples_bad.md`
- keep reference files one hop away from `SKILL.md`; avoid deep reference chains

4. Put contracts into `assets/`
- store machine-readable schemas, templates, or static resource packs in `assets/`
- use `assets/schema.json` for the structured artifact that the skill validates or emits

5. Keep `scripts/run.py` deterministic
- allow file discovery, normalization, validation, manifest generation, and external tool calls
- keep prose templates, domain defaults, and reader-facing judgment out of Python

6. Validate hygiene before reuse
- make sure the package has no unresolved placeholders in reader-facing examples
- make sure `SKILL.md` explicitly tells the agent when to read each reference file

## When to read `references/`

- Always read `references/overview.md` before customizing or applying this template.
- Read `references/examples_good.md` when the skill writes reader-facing text or shapes another writer skill.
- Read `references/examples_bad.md` when cleaning up generator voice, pipeline jargon, or weak deliverable framing.
- If the skill has domain variants, add explicit domain-pack references and mention the selection rule here.

## Assets to reuse

- `assets/schema.json`: a generic contract for a reference-first skill manifest; adapt it to the concrete skill you are building.

## Script role

- `scripts/run.py` is a minimal validator and manifest builder.
- Read or patch the script only when you need deterministic behavior.
- Do not rely on the script to supply the skill's method, voice, domain taxonomy, or reader-facing examples.

## Block conditions

Stop and fix the package before reuse if any of these are true:
- `SKILL.md` duplicates long reference content instead of routing to `references/`
- `run.py` contains domain defaults, sentence libraries, or filler prose
- reader-facing examples contain unresolved placeholders or internal pipeline jargon
- the schema does not match the artifact the skill is supposed to validate or emit

## Done checklist

- `SKILL.md` stays lean and references other files explicitly
- `references/` contains the actual method and exemplars
- `assets/` contains machine-readable contracts only
- `scripts/run.py` stays deterministic and small
- the package can be understood by reading `SKILL.md` and the referenced files without reading all Python first