fill-protocol

Name: fill-protocol
Author: Aperivue

208stars53forks

How to install fill-protocol?

aperivue/medsci-skills/fill-protocol

$npx -y skills add Aperivue/medsci-skills --skill fill-protocol

Installs into the current project.

Summary

Fill institutional Word form templates (.doc/.docx) for IRB protocols, ethics applications, grant proposals, and other structured research documents while preserving the original styles, table layouts, fonts, and page geometry. Pairs with write-protocol — write-protocol drafts th

Files · 1

View on GitHub

SKILL.md

1	# Fill-Protocol Skill
2
3	You are helping a researcher populate an institutional Word form (IRB protocol,
4	ethics application, grant proposal, etc.) without breaking the original document
5	formatting. This skill is the formatting counterpart to `write-protocol`: where
6	`write-protocol` drafts content, `fill-protocol` lays that content into the
7	institutional template.
8
9	## Why This Skill Exists
10
11	Recreating institutional forms from scratch with `python-docx` reliably destroys
12	table layouts, page breaks, and font consistency. The only safe approach is to
13	open the existing template and replace cell/paragraph text in place. This
14	skill enforces that pattern.
15
16	## Core Principles (Do Not Violate)
17
18	1. Open the existing template — never create from scratch. Use
19	`Document(template_path)`, not `Document()`.
20	2. Convert .doc → .docx via LibreOffice headless before any editing.
21	`pandoc -f doc` is not supported; `textutil` corrupts table structure.
22	3. Match cells by left-label text, not row/column coordinates. Templates
23	evolve and coordinate matching breaks silently.
24	4. Apply `cantSplit` to every filled row so a row never breaks across pages.
25	5. For CJK languages, set the `eastAsia` font attribute, not just
26	`run.font.name`. Hangul/Kanji/Hanzi will render in fallback fonts otherwise.
27	6. Validate every fill operation: report unmatched labels, count empty cells,
28	and surface mismatches before saving.
29
30	## Dependencies
31
32	If the template is already `.docx`, LibreOffice is not required — only the
33	three Python packages below. LibreOffice is needed only when the template is a
34	legacy `.doc` and must be converted first.
35
36	```bash
37	# Python libraries (always required)
38	pip install --user docxtpl python-docx pyyaml
39
40	# LibreOffice (only for legacy .doc input; ~700 MB on macOS)
41	brew install --cask libreoffice # macOS
42	sudo apt-get install -y libreoffice # Debian/Ubuntu
43	sudo dnf install -y libreoffice # Fedora
44	sudo pacman -S --needed libreoffice-fresh # Arch
45	```
46
47	### Bundled setup script
48
49	The skill ships a `setup.sh` that detects what is missing and installs only
50	those parts, with a confirmation prompt before each step:
51
52	```bash
53	bash setup.sh check # report what's installed (read-only)
54	bash setup.sh install # install missing pieces (asks before each)
55	```
56
57	### Auto-install behavior (for Claude as the caller)
58
59	When invoking this skill on behalf of a user:
60
61	1. Before calling `doc_to_docx.py`, run `bash setup.sh check`. If
62	LibreOffice is missing, ask the user before installing — the cask is
63	~700 MB and proceeding silently is unfriendly.
64	2. Skip LibreOffice entirely if the template is already `.docx`. Only
65	surface the install prompt when a `.doc` is encountered.
66	3. Never pass `--yes` to `setup.sh install` unless the user has explicitly
67	authorized unattended installation in this session.
68	4. If the user declines installation, fall back to asking them to convert
69	the `.doc` manually (open in Word/LibreOffice/Pages → Save As → .docx) and
70	then re-run with the converted file.
71
72	## Workflow
73
74	### Step 1 — Convert legacy .doc to .docx (if needed)
75
76	```bash
77	python scripts/doc_to_docx.py path/to/template.doc path/to/template.docx
78	```
79
80	### Step 2 — Inspect the template structure
81
82	```bash
83	python scripts/inspect_template.py path/to/template.docx
84	```
85
86	This lists every table, every cell (with row/column coordinates and content
87	preview), and every top-level paragraph. Use this output to identify the labels
88	you will match against in your YAML content file.
89
90	### Step 3 — Author a content YAML
91
92	The YAML supports three fill modes. All keys are optional.
93
94	```yaml
95	protections:
96	korean_font: "맑은 고딕" # CJK font (set to "Noto Sans CJK KR", "SimSun",
97	# "MS Mincho", etc. for other locales)
98	cant_split: true # Apply <w:cantSplit/> to every filled row
99
100	# Readability options (see "Readability" section below for full semantics)
101	blank_between_paragraphs: true # default true — Enter between \n\n chunks
102	blank_around_section_header: true # default true — Enter above/below filled sections
103	blank_around_all_section_headers: false # default false — opt-in; also touches untouched sections
104
105	# M

People who liked this also viewed

6 picks

Type

fill-protocol

208stars53forks

View on GitHub

How to install fill-protocol?

aperivue/medsci-skills/fill-protocol

$npx -y skills add Aperivue/medsci-skills --skill fill-protocol

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Fill-Protocol Skill
2
3	You are helping a researcher populate an institutional Word form (IRB protocol,
4	ethics application, grant proposal, etc.) without breaking the original document
5	formatting. This skill is the formatting counterpart to `write-protocol`: where
6	`write-protocol` drafts content, `fill-protocol` lays that content into the
7	institutional template.
8
9	## Why This Skill Exists
10
11	Recreating institutional forms from scratch with `python-docx` reliably destroys
12	table layouts, page breaks, and font consistency. The only safe approach is to
13	open the existing template and replace cell/paragraph text in place. This
14	skill enforces that pattern.
15
16	## Core Principles (Do Not Violate)
17
18	1. Open the existing template — never create from scratch. Use
19	`Document(template_path)`, not `Document()`.
20	2. Convert .doc → .docx via LibreOffice headless before any editing.
21	`pandoc -f doc` is not supported; `textutil` corrupts table structure.
22	3. Match cells by left-label text, not row/column coordinates. Templates
23	evolve and coordinate matching breaks silently.
24	4. Apply `cantSplit` to every filled row so a row never breaks across pages.
25	5. For CJK languages, set the `eastAsia` font attribute, not just
26	`run.font.name`. Hangul/Kanji/Hanzi will render in fallback fonts otherwise.
27	6. Validate every fill operation: report unmatched labels, count empty cells,
28	and surface mismatches before saving.
29
30	## Dependencies
31
32	If the template is already `.docx`, LibreOffice is not required — only the
33	three Python packages below. LibreOffice is needed only when the template is a
34	legacy `.doc` and must be converted first.
35
36	```bash
37	# Python libraries (always required)
38	pip install --user docxtpl python-docx pyyaml
39
40	# LibreOffice (only for legacy .doc input; ~700 MB on macOS)
41	brew install --cask libreoffice # macOS
42	sudo apt-get install -y libreoffice # Debian/Ubuntu
43	sudo dnf install -y libreoffice # Fedora
44	sudo pacman -S --needed libreoffice-fresh # Arch
45	```
46
47	### Bundled setup script
48
49	The skill ships a `setup.sh` that detects what is missing and installs only
50	those parts, with a confirmation prompt before each step:
51
52	```bash
53	bash setup.sh check # report what's installed (read-only)
54	bash setup.sh install # install missing pieces (asks before each)
55	```
56
57	### Auto-install behavior (for Claude as the caller)
58
59	When invoking this skill on behalf of a user:
60
61	1. Before calling `doc_to_docx.py`, run `bash setup.sh check`. If
62	LibreOffice is missing, ask the user before installing — the cask is
63	~700 MB and proceeding silently is unfriendly.
64	2. Skip LibreOffice entirely if the template is already `.docx`. Only
65	surface the install prompt when a `.doc` is encountered.
66	3. Never pass `--yes` to `setup.sh install` unless the user has explicitly
67	authorized unattended installation in this session.
68	4. If the user declines installation, fall back to asking them to convert
69	the `.doc` manually (open in Word/LibreOffice/Pages → Save As → .docx) and
70	then re-run with the converted file.
71
72	## Workflow
73
74	### Step 1 — Convert legacy .doc to .docx (if needed)
75
76	```bash
77	python scripts/doc_to_docx.py path/to/template.doc path/to/template.docx
78	```
79
80	### Step 2 — Inspect the template structure
81
82	```bash
83	python scripts/inspect_template.py path/to/template.docx
84	```
85
86	This lists every table, every cell (with row/column coordinates and content
87	preview), and every top-level paragraph. Use this output to identify the labels
88	you will match against in your YAML content file.
89
90	### Step 3 — Author a content YAML
91
92	The YAML supports three fill modes. All keys are optional.
93
94	```yaml
95	protections:
96	korean_font: "맑은 고딕" # CJK font (set to "Noto Sans CJK KR", "SimSun",
97	# "MS Mincho", etc. for other locales)
98	cant_split: true # Apply <w:cantSplit/> to every filled row
99
100	# Readability options (see "Readability" section below for full semantics)
101	blank_between_paragraphs: true # default true — Enter between \n\n chunks
102	blank_around_section_header: true # default true — Enter above/below filled sections
103	blank_around_all_section_headers: false # default false — opt-in; also touches untouched sections
104
105	# M

People who liked this also viewed

6 picks

Type