# Template Reference First

> Internal template for creating or refactoring a skill into the repository's reference-first shape. **Trigger**: reference-first template, blueprint skill, create a reusable skill, refactor a script-heavy skill. **Use when**: you need a lean `SKILL.md`, explicit `references/`, machine-readable `assets/`, and a minimal deterministic `run.py`.

- Skill: `willoscar/template-reference-first` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds add willoscar/template-reference-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willoscar/template-reference-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: WILLOSCAR (https://skillmd.com/u/willoscar)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/willoscar/template-reference-first

---


# 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