_template_reference_first

Name: _template_reference_first
Author: WILLOSCAR

489stars39forks

How to install _template_reference_first?

willoscar/research-units-pipeline-skills/_template_reference_first

$npx -y skills add WILLOSCAR/research-units-pipeline-skills --skill _template_reference_first

Installs into the current project.

Summary

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/, mac

Files · 1

View on GitHub

SKILL.md

1	# Reference-First Skill Template
2
3	## Why this exists
4
5	This package is the default starting point for new or refactored skills in this repo.
6
7	It demonstrates the intended split of responsibilities:
8	- `SKILL.md` routes the workflow
9	- `references/` holds method, judgment, and exemplars
10	- `assets/` holds machine-readable contracts
11	- `scripts/` handles deterministic execution only
12
13	Use it as a shape to copy and customize, not as a domain-specific skill.
14
15	## Inputs
16
17	- the job the skill should encode
18	- the expected inputs and outputs for that job
19	- acceptance criteria and failure conditions
20	- any domain packs, schemas, or existing artifacts that must be reused
21
22	## Outputs
23
24	- a lean `SKILL.md`
25	- `references/overview.md`
26	- `references/examples_good.md`
27	- `references/examples_bad.md`
28	- `assets/schema.json`
29	- `scripts/run.py`
30
31	## Workflow
32
33	1. Define the job and its boundary
34	- write down the trigger, intended outcome, and explicit non-goals
35	- separate reusable behavior from one-off project context
36
37	2. Write `SKILL.md` as a router
38	- keep only the activation rule, inputs, outputs, workflow, block conditions, and resource routing
39	- do not copy large judgment rules, domain essays, or sentence banks into this file
40
41	3. Move reusable thinking into `references/`
42	- put domain knowledge, decision rubrics, and method notes in `references/overview.md`
43	- if the skill can emit reader-facing text, include both `references/examples_good.md` and `references/examples_bad.md`
44	- keep reference files one hop away from `SKILL.md`; avoid deep reference chains
45
46	4. Put contracts into `assets/`
47	- store machine-readable schemas, templates, or static resource packs in `assets/`
48	- use `assets/schema.json` for the structured artifact that the skill validates or emits
49
50	5. Keep `scripts/run.py` deterministic
51	- allow file discovery, normalization, validation, manifest generation, and external tool calls
52	- keep prose templates, domain defaults, and reader-facing judgment out of Python
53
54	6. Validate hygiene before reuse
55	- make sure the package has no unresolved placeholders in reader-facing examples
56	- make sure `SKILL.md` explicitly tells the agent when to read each reference file
57
58	## When to read `references/`
59
60	- Always read `references/overview.md` before customizing or applying this template.
61	- Read `references/examples_good.md` when the skill writes reader-facing text or shapes another writer skill.
62	- Read `references/examples_bad.md` when cleaning up generator voice, pipeline jargon, or weak deliverable framing.
63	- If the skill has domain variants, add explicit domain-pack references and mention the selection rule here.
64
65	## Assets to reuse
66
67	- `assets/schema.json`: a generic contract for a reference-first skill manifest; adapt it to the concrete skill you are building.
68
69	## Script role
70
71	- `scripts/run.py` is a minimal validator and manifest builder.
72	- Read or patch the script only when you need deterministic behavior.
73	- Do not rely on the script to supply the skill's method, voice, domain taxonomy, or reader-facing examples.
74
75	## Block conditions
76
77	Stop and fix the package before reuse if any of these are true:
78	- `SKILL.md` duplicates long reference content instead of routing to `references/`
79	- `run.py` contains domain defaults, sentence libraries, or filler prose
80	- reader-facing examples contain unresolved placeholders or internal pipeline jargon
81	- the schema does not match the artifact the skill is supposed to validate or emit
82
83	## Done checklist
84
85	- `SKILL.md` stays lean and references other files explicitly
86	- `references/` contains the actual method and exemplars
87	- `assets/` contains machine-readable contracts only
88	- `scripts/run.py` stays deterministic and small
89	- the package can be understood by reading `SKILL.md` and the referenced files without reading all Python first

People who liked this also viewed

6 picks

Type

_template_reference_first

489stars39forks

View on GitHub

How to install _template_reference_first?

willoscar/research-units-pipeline-skills/_template_reference_first

$npx -y skills add WILLOSCAR/research-units-pipeline-skills --skill _template_reference_first

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Reference-First Skill Template
2
3	## Why this exists
4
5	This package is the default starting point for new or refactored skills in this repo.
6
7	It demonstrates the intended split of responsibilities:
8	- `SKILL.md` routes the workflow
9	- `references/` holds method, judgment, and exemplars
10	- `assets/` holds machine-readable contracts
11	- `scripts/` handles deterministic execution only
12
13	Use it as a shape to copy and customize, not as a domain-specific skill.
14
15	## Inputs
16
17	- the job the skill should encode
18	- the expected inputs and outputs for that job
19	- acceptance criteria and failure conditions
20	- any domain packs, schemas, or existing artifacts that must be reused
21
22	## Outputs
23
24	- a lean `SKILL.md`
25	- `references/overview.md`
26	- `references/examples_good.md`
27	- `references/examples_bad.md`
28	- `assets/schema.json`
29	- `scripts/run.py`
30
31	## Workflow
32
33	1. Define the job and its boundary
34	- write down the trigger, intended outcome, and explicit non-goals
35	- separate reusable behavior from one-off project context
36
37	2. Write `SKILL.md` as a router
38	- keep only the activation rule, inputs, outputs, workflow, block conditions, and resource routing
39	- do not copy large judgment rules, domain essays, or sentence banks into this file
40
41	3. Move reusable thinking into `references/`
42	- put domain knowledge, decision rubrics, and method notes in `references/overview.md`
43	- if the skill can emit reader-facing text, include both `references/examples_good.md` and `references/examples_bad.md`
44	- keep reference files one hop away from `SKILL.md`; avoid deep reference chains
45
46	4. Put contracts into `assets/`
47	- store machine-readable schemas, templates, or static resource packs in `assets/`
48	- use `assets/schema.json` for the structured artifact that the skill validates or emits
49
50	5. Keep `scripts/run.py` deterministic
51	- allow file discovery, normalization, validation, manifest generation, and external tool calls
52	- keep prose templates, domain defaults, and reader-facing judgment out of Python
53
54	6. Validate hygiene before reuse
55	- make sure the package has no unresolved placeholders in reader-facing examples
56	- make sure `SKILL.md` explicitly tells the agent when to read each reference file
57
58	## When to read `references/`
59
60	- Always read `references/overview.md` before customizing or applying this template.
61	- Read `references/examples_good.md` when the skill writes reader-facing text or shapes another writer skill.
62	- Read `references/examples_bad.md` when cleaning up generator voice, pipeline jargon, or weak deliverable framing.
63	- If the skill has domain variants, add explicit domain-pack references and mention the selection rule here.
64
65	## Assets to reuse
66
67	- `assets/schema.json`: a generic contract for a reference-first skill manifest; adapt it to the concrete skill you are building.
68
69	## Script role
70
71	- `scripts/run.py` is a minimal validator and manifest builder.
72	- Read or patch the script only when you need deterministic behavior.
73	- Do not rely on the script to supply the skill's method, voice, domain taxonomy, or reader-facing examples.
74
75	## Block conditions
76
77	Stop and fix the package before reuse if any of these are true:
78	- `SKILL.md` duplicates long reference content instead of routing to `references/`
79	- `run.py` contains domain defaults, sentence libraries, or filler prose
80	- reader-facing examples contain unresolved placeholders or internal pipeline jargon
81	- the schema does not match the artifact the skill is supposed to validate or emit
82
83	## Done checklist
84
85	- `SKILL.md` stays lean and references other files explicitly
86	- `references/` contains the actual method and exemplars
87	- `assets/` contains machine-readable contracts only
88	- `scripts/run.py` stays deterministic and small
89	- the package can be understood by reading `SKILL.md` and the referenced files without reading all Python first

People who liked this also viewed

6 picks

Type