name	write-missing-core-words
description	Batch author missing vocabulary MDX files for the gpt-wordbook project. Use when Codex needs to fill entries listed in scripts/missing-core.json, create or revise src/content/docs/words/*.mdx in the house style, plan safe writing batches, or verify that generated word pages match the required structure.

Write Missing Core Words

Use this skill to add missing core vocabulary pages without re-discovering the workflow every time.

Quick Start

Select the next batch:

node .codex/skills/write-missing-core-words/scripts/next-batch.mjs --limit 15

If you want a reusable manifest for the batch, write one:

node .codex/skills/write-missing-core-words/scripts/next-batch.mjs \
  --limit 15 \
  --manifest /tmp/missing-core-batch.json

Read the style references before writing:
- src/content/docs/words/better.mdx
- references/entry-template.md
- references/batch-playbook.md
Create one MDX file per selected word under src/content/docs/words/.
Validate the batch:

node .codex/skills/write-missing-core-words/scripts/verify-word-batch.mjs \
  --manifest /tmp/missing-core-batch.json

Workflow

1. Plan a small batch

Default to 10-20 words per batch.
Go above 20 only when the user explicitly prioritizes throughput over reviewability.
Do not edit scripts/missing-core.json; treat it as the source of truth.
Do not overwrite unrelated user changes in the workspace.

2. Author files in the project format

For each selected word:

Create src/content/docs/words/<word>.mdx.
Keep the filename lowercase.
Capitalize the first letter in frontmatter title.
Keep this frontmatter shape:

---
title: Word
description: ...
sidebar:
  hidden: true
tableOfContents: false
---

Always import Pronunciation from ../../../components/Pronunciation.svelte.
Import WordRelations only when at least one synonym or antonym is present.
Keep section order exactly as shown in references/entry-template.md.
Write explanations in Chinese.
Keep example sentences in English and translations in Chinese.
Prefer natural, high-frequency meanings and collocations over rare senses.
Prefer conservative etymology. If a root story is uncertain, stay factual and avoid speculative pseudo-analysis.

3. Follow content guardrails

Avoid placeholders such as Example sentence, 需要进一步研究, common collocation, or A short story using ....
Avoid empty WordRelations arrays. Omit the component instead.
Prefer 2-5 synonyms and 1-4 antonyms, using simple lemma forms when possible.
Keep the page helpful for learners: concrete usage, concise explanations, practical collocations, memorable examples.
Prefer relation words that are likely to have entries in this repo, but do not block on perfect coverage.

4. Validate immediately after writing

Run verify-word-batch.mjs on the exact batch you created.
Fix structure issues before moving to the next batch.
If you changed many files or touched shared components, run pnpm build.

Helper Scripts

`scripts/next-batch.mjs`

Use this script to compute the next writable batch from scripts/missing-core.json.

Supported flags:

--limit <n>: number of words to select, default 20
--offset <n>: skip this many remaining words before selecting
--from <word>: start from a specific remaining word
--manifest <path>: write the selection to a JSON manifest
--json: print machine-readable JSON

`scripts/verify-word-batch.mjs`

Use this script to validate newly created files.

Supported flags:

--words word1,word2: validate an explicit word list
--manifest <path>: validate the selectedWords from a manifest

The validator checks:

file existence
required frontmatter fields
required headings in order
Pronunciation import and component usage
WordRelations import/component consistency
at least three numbered examples
common placeholder text that should be replaced

Recovery Pattern

If validation fails, fix the files first instead of continuing with the next batch.
If a word already exists by the time you start writing, skip it and continue.
If a word is hard to analyze confidently, write a simpler but accurate learner-friendly entry instead of forcing a speculative deep dive.

name	write-missing-core-words
description	Batch author missing vocabulary MDX files for the gpt-wordbook project. Use when Codex needs to fill entries listed in scripts/missing-core.json, create or revise src/content/docs/words/*.mdx in the house style, plan safe writing batches, or verify that generated word pages match the required structure.

Write Missing Core Words

Use this skill to add missing core vocabulary pages without re-discovering the workflow every time.

Quick Start

Select the next batch:

node .codex/skills/write-missing-core-words/scripts/next-batch.mjs --limit 15

If you want a reusable manifest for the batch, write one:

node .codex/skills/write-missing-core-words/scripts/next-batch.mjs \
  --limit 15 \
  --manifest /tmp/missing-core-batch.json

Read the style references before writing:
- src/content/docs/words/better.mdx
- references/entry-template.md
- references/batch-playbook.md
Create one MDX file per selected word under src/content/docs/words/.
Validate the batch:

node .codex/skills/write-missing-core-words/scripts/verify-word-batch.mjs \
  --manifest /tmp/missing-core-batch.json

Workflow

1. Plan a small batch

Default to 10-20 words per batch.
Go above 20 only when the user explicitly prioritizes throughput over reviewability.
Do not edit scripts/missing-core.json; treat it as the source of truth.
Do not overwrite unrelated user changes in the workspace.

2. Author files in the project format

For each selected word:

Create src/content/docs/words/<word>.mdx.
Keep the filename lowercase.
Capitalize the first letter in frontmatter title.
Keep this frontmatter shape:

---
title: Word
description: ...
sidebar:
  hidden: true
tableOfContents: false
---

Always import Pronunciation from ../../../components/Pronunciation.svelte.
Import WordRelations only when at least one synonym or antonym is present.
Keep section order exactly as shown in references/entry-template.md.
Write explanations in Chinese.
Keep example sentences in English and translations in Chinese.
Prefer natural, high-frequency meanings and collocations over rare senses.
Prefer conservative etymology. If a root story is uncertain, stay factual and avoid speculative pseudo-analysis.

3. Follow content guardrails

Avoid placeholders such as Example sentence, 需要进一步研究, common collocation, or A short story using ....
Avoid empty WordRelations arrays. Omit the component instead.
Prefer 2-5 synonyms and 1-4 antonyms, using simple lemma forms when possible.
Keep the page helpful for learners: concrete usage, concise explanations, practical collocations, memorable examples.
Prefer relation words that are likely to have entries in this repo, but do not block on perfect coverage.

4. Validate immediately after writing

Run verify-word-batch.mjs on the exact batch you created.
Fix structure issues before moving to the next batch.
If you changed many files or touched shared components, run pnpm build.

Helper Scripts

`scripts/next-batch.mjs`

Use this script to compute the next writable batch from scripts/missing-core.json.

Supported flags:

--limit <n>: number of words to select, default 20
--offset <n>: skip this many remaining words before selecting
--from <word>: start from a specific remaining word
--manifest <path>: write the selection to a JSON manifest
--json: print machine-readable JSON

`scripts/verify-word-batch.mjs`

Use this script to validate newly created files.

Supported flags:

--words word1,word2: validate an explicit word list
--manifest <path>: validate the selectedWords from a manifest

The validator checks:

file existence
required frontmatter fields
required headings in order
Pronunciation import and component usage
WordRelations import/component consistency
at least three numbered examples
common placeholder text that should be replaced

Recovery Pattern

If validation fails, fix the files first instead of continuing with the next batch.
If a word already exists by the time you start writing, skip it and continue.
If a word is hard to analyze confidently, write a simpler but accurate learner-friendly entry instead of forcing a speculative deep dive.