@1aboveio/core-skills 0.1.28 → 0.1.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1aboveio/core-skills",
3
- "version": "0.1.28",
3
+ "version": "0.1.29",
4
4
  "description": "Shared writing and document foundation: house style, plain-language replies, editorial review, Chinese polish, terminology, write-doc, write-report, distill-writing, doc-to-md and reg-parser.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -27,7 +27,7 @@
27
27
  "id": "core",
28
28
  "core": "@1aboveio/core-skills",
29
29
  "coreSkills": [],
30
- "digest": "69108e05ada779a4f433391e1bfe7e5c7bd639872aace63a5c1b098fd808047b"
30
+ "digest": "31e3197415326845b8bf6393468f283087151accfb56acf73df983db70df67b6"
31
31
  },
32
32
  "publishConfig": {
33
33
  "registry": "https://registry.npmjs.org/",
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: distill-writing
3
3
  description: "Learn a house writing style from approved sample documents, or save an explicitly stated project document preference, into WRITING.md and writing/templates/. Use for sample-based style learning, house-style setup or refresh, and requests such as 'remember this for future PRDs' or 'make this our report default', including handoffs from write-doc, write-report or plain-language. Preserve manual edits and separate document types. NOT for drafting a document (write-doc) or analytical report (write-report) or saving chat-only preferences (plain-language)."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Distill a writing style
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: doc-to-md
3
3
  description: "Convert documents (PDF, DOCX, PPTX, XLSX, images) to Markdown so agents can read them. Use as the preprocessing step whenever binary files need to enter agent context — contract review, compliance audit, document analysis, evidence review."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # doc-to-md
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: editorial-review
3
3
  description: "Review a document or generated report for what it says (does the reader get the answer, is the argument sound, is anything unsupported, obvious or repeated), then fix the content. Use to review, tighten or clarify a doc or report, and as the review step of write-doc, write-report and domain report skills. NOT for Chinese wording (polish-cn) or code review (better-review)."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Editorial review
@@ -3,7 +3,7 @@ name: house-style
3
3
  description: "Shared reference the writing skills read by path: WRITING.md lookup and precedence, template choice, gap markers, template shape, the bundled templates, and the default English and Chinese style guides. Never select or invoke it as a task."
4
4
  disable-model-invocation: true
5
5
  user-invocable: false
6
- release-version: 0.50.8
6
+ release-version: 0.50.9
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # House style
@@ -14,6 +14,7 @@ skill on its own. Writing a document → `write-doc`; an analytical report → `
14
14
 
15
15
  | Need | Read |
16
16
  | --- | --- |
17
+ | Common language principles, factual precision and direct statements instead of self-defense | [shared language rules](../plain-language/references/language.md), shipped by plain-language |
17
18
  | Where WRITING.md is, which template, which rule wins, gap markers, template shape, who edits what | [rules](references/rules.md) |
18
19
  | Explicitly save a document preference from write-doc, write-report or plain-language | [persistence](references/persistence.md), owned by distill-writing |
19
20
  | Actual user /write-doc or /write-report invocation initializes missing local guidance | [initialization](references/initialization.md), a bounded writer-owned setup, not style learning |
@@ -5,6 +5,10 @@ These examples show form, not facts to copy. Apply them with
5
5
 
6
6
  ## Defensive wording
7
7
 
8
+ Read and apply the [shared language rules](../../plain-language/references/language.md)
9
+ for the general distinction between self-defense and material qualifications. The examples
10
+ below apply that distinction to analytical reports.
11
+
8
12
  Do not append "not causal," "future results are unknown," or "no action was taken" to every
9
13
  finding. Keep the specific restriction when a reader might otherwise infer a stronger claim.
10
14
  Non-execution belongs in the report when action status itself is the reader's question.
@@ -1,5 +1,9 @@
1
1
  # Initialize guidance on an explicit writing invocation
2
2
 
3
+ First read and follow the [local setup convention](../../plain-language/references/setup.md)
4
+ in full. It also applies to plain-language and owns the trigger, current-directory scope,
5
+ shared-language reference, inheritance and loading-pointer requirements.
6
+
3
7
  An actual user invocation of `/write-doc` or `/write-report`, including fast mode or an
4
8
  initialization-only request, authorizes this bounded local setup before drafting. Automatic
5
9
  skill selection, a domain skill calling the writer, reading its instructions, or a slash command
@@ -14,10 +18,10 @@ directions as project defaults. Explicit future-document preferences still follo
14
18
 
15
19
  ## Resolve and preview
16
20
 
17
- Start beside the primary input, else the requested output, else the working directory, following
18
- [the lookup rules](rules.md#find-writingmd). Use an explicitly named narrower client/project
19
- directory as the write scope; otherwise the nearest Git root, or the start directory without
20
- one. An inherited guide outside that scope is readable, not writable. Never initialize global
21
+ Start in the current working directory, or the setup directory explicitly named by the user.
22
+ Use that directory as the write scope; input/output paths do not choose setup scope. Use
23
+ [the lookup rules](rules.md#find-writingmd) to read existing guidance. An inherited guide
24
+ outside that scope is readable, not writable. Never initialize global
21
25
  or home-level guidance. Read the applicable guide and existing terminology before setup.
22
26
  If the output directory does not yet exist, resolve lookup from its nearest existing parent;
23
27
  do not widen an explicitly named client scope to make setup succeed.
@@ -25,8 +29,7 @@ do not widen an explicitly named client scope to make setup succeed.
25
29
  Run the bundled helper from its installed location:
26
30
 
27
31
  ```sh
28
- node {house-style baseDir}/scripts/init-guidance.mjs --start START_DIRECTORY
29
- # Add --scope CLIENT_DIRECTORY when the user named a narrower scope.
32
+ node {house-style baseDir}/scripts/init-guidance.mjs --start SETUP_DIRECTORY
30
33
  ```
31
34
 
32
35
  Inspect the JSON preview. Confirm the destinations stay within the authorized scope and that
@@ -35,9 +38,8 @@ out-of-scope write-target links and conflicting write targets block setup; do no
35
38
  install another skill, or silently select a different guide. Continue unaffected document work when possible and
36
39
  report the setup gap. Do not claim persistence is configured after a partial write.
37
40
  Existing linked templates outside the write scope may be read but are never changed by setup.
38
- If an explicitly narrower scope would create a new guide that shadows an inherited guide,
39
- surface that policy change and obtain the scope decision before applying it; do not silently
40
- discard the inherited rules merely to create two local files.
41
+ If a local guide would shadow inherited guidance, preserve that guidance through an explicit
42
+ relative inheritance link in the new guide. Do not copy or modify the inherited guide.
41
43
 
42
44
  ## Apply once, then write
43
45
 
@@ -46,8 +48,8 @@ approval is needed for the setup the explicit invocation already requested. The
46
48
 
47
49
  - Creates missing `WRITING.md` and `TERMINOLOGY.md` together, even when no project-specific
48
50
  terms are known. A small terminology skeleton is valid here; it is not permission to invent
49
- rows. Existing guide bytes remain unchanged.
50
- - Adds only the loading pointers needed in local `AGENTS.md` and supported `CLAUDE.md`
51
+ rows. Existing guide content is preserved; only a missing shared-language reference is appended.
52
+ - Adds the document and shared-language loading pointers needed in local `AGENTS.md` and supported `CLAUDE.md`
51
53
  entrypoints. It preserves valid in-scope links and edits a shared target once; missing
52
54
  `CLAUDE.md` becomes a relative link to `AGENTS.md`.
53
55
  - Reports files created, updated or already configured, the scope, inherited guidance and
@@ -45,7 +45,9 @@ terms" goes in `writing/templates/commercial-proposal.md`.
45
45
  file) starts in the input file's directory instead: the client's house style sits with the
46
46
  client's files. Pasted input: start in the output directory, else the working directory.
47
47
  2. Walk up one directory at a time. The first `WRITING.md` found applies. Do not merge it with a
48
- `WRITING.md` further up.
48
+ `WRITING.md` further up unless it explicitly links an inherited writing guide. Follow that
49
+ link first, then apply local additions. Automatic local setup preserves inherited policy
50
+ through this explicit link; ordinary lookup does not merge unlinked ancestor guides.
49
51
  3. Stop at the project root: the nearest ancestor containing `.git`. With no `.git` above the start,
50
52
  keep walking up, but never use a `WRITING.md` in the user's home directory or any directory
51
53
  above it.
@@ -7,6 +7,10 @@ version of a bilingual document. WRITING.md and the template override them
7
7
 
8
8
  Write so a busy expert understands on the first read.
9
9
 
10
+ First read and apply the [shared language rules](../../plain-language/references/language.md)
11
+ in full, including direct statements instead of self-defense. They own the common rules
12
+ for replies and documents; this guide adds document-specific voice, examples and conventions.
13
+
10
14
  ## Contents
11
15
 
12
16
  - [Three rules above the rest](#three-rules-above-the-rest)
@@ -54,7 +58,10 @@ trade-offs add up to. A reference section or a policy statement stays neutral.
54
58
  - Most sentences under 25 words; instructions under 20.
55
59
  - Present tense for how things are. "Will" only for what happens later.
56
60
  - Put the common case first and exceptions after.
57
- - Write full sentences, not telegraphic notes. Keep the words that carry the logic: if,
61
+ - Write full sentences, not telegraphic notes. Include a subject and a predicate in prose:
62
+ say who or what does, is or experiences something. Avoid fragments that omit both.
63
+ Headings and labels may remain phrases; commands may use an understood subject.
64
+ Keep the words that carry the logic: if,
58
65
  when, because, but. Without them a rule becomes a label the reader has to decode.
59
66
  Example: "It is 0 if there were no collections," not "0 when none."
60
67
  - Introduce a list with a complete sentence; keep list items parallel.
@@ -4,6 +4,9 @@
4
4
  ([优先级](rules.md#resolve-conflicting-instructions));与语言无关的结构与版式规则见
5
5
  [defaults](defaults.md)。
6
6
 
7
+ 先完整读取并应用[共用语言规范](../../plain-language/references/language.md),包括直接陈述、避免自辩的规则。
8
+ 共用文件负责回复和文档通用的语言原则;本文件补充文档语气、示例和中文排版约定。
9
+
7
10
  本文件以 [Fenng/tech-doc-style-chinese](https://github.com/Fenng/tech-doc-style-chinese)(MIT)为基础改编,版权与许可声明见文末。
8
11
 
9
12
  ## 目录
@@ -43,13 +46,14 @@
43
46
  - 准确先于修辞,清晰先于热闹。使用克制、直接、可执行的中文。
44
47
  - 先回答「是什么、适用于什么、需要做什么、接着看哪里」。
45
48
  - 不写问候式开场、宣传口号和空泛形容。
46
- - 技术文档默认不直接称呼读者,使用无主句或明确角色(开发者、实施人员、业务负责人)。WRITING.md 可改为「您」或「你」。
49
+ - 技术文档默认不直接称呼读者,正文使用明确的角色或对象作为主语(开发者、实施人员、系统、指标)。操作指令可以省略明确的执行者,但要保留动作和对象。WRITING.md 可改为「您」或「你」。
47
50
  - 一个段落承载一个主要信息点;段落源文件保持一段一行,不硬换行。
48
51
 
49
52
  ## 结构与句子
50
53
 
51
54
  - 一个句子保持一个清晰主干,不连续堆叠条件、动作和例外。
52
- - 写完整的句子,不写电报体:保留表达逻辑的词,包括条件(若……则、当……时)、因果(因为、所以)和转折(但)。省掉这些词,规则就成了要读者自己解码的标签。示例:`若窗口内无收款,则为 0`,而不是 `无收款为 0`;`付款人名称为空的收款不计入`,而不是 `空值不计`。
55
+ - 写完整的句子,不写电报体:正文要有主语和谓语,写清楚谁做什么、什么是什么,或什么处于什么状态。避免主语和谓语同时缺失的标签串。标题、字段名和紧凑表格中的标签可以使用短语。
56
+ - 保留表达逻辑的词,包括条件(若……则、当……时)、因果(因为、所以)和转折(但)。示例:`若窗口内无收款,则该指标的值为 0`,而不是 `无收款为 0`;`付款人名称为空的收款不计入`,而不是 `空值不计`。
53
57
  - 标题说明用途或结论,不只写抽象名词。示例:`退单量在调价后翻倍`,而不是 `分析`。
54
58
  - 列表项保持相同层级、句式和信息密度;完整句式的列表项统一加句号。
55
59
  - 指代可能不清时,用具体名称替代「该」「其」「此」「上述」「相关」。
@@ -3,9 +3,12 @@ import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import os from 'node:os';
5
5
 
6
- const WRITING = '<!-- writing-md: 1 -->\n# Writing guide\n\nProject document preferences are not yet saved; bundled defaults apply.\n\n## Terms\n\nTerms: see [TERMINOLOGY.md](TERMINOLOGY.md).\n';
6
+ const LANGUAGE = '## Shared language rules\n\nDefault: read and apply `plain-language/references/language.md` from the installed `plain-language` skill for replies, documents and reports. Keep document structures and workflows with their owning skills.\n';
7
+ const REPLIES = '## Agent replies\n\nDefault: use `plain-language` for replies and status updates. A user-requested style change lasts for the current session only.\n';
8
+ const WRITING = '<!-- writing-md: 1 -->\n# Writing guide\n\n' + LANGUAGE + '\n' + REPLIES + '\n## Terms\n\nTerms: see [TERMINOLOGY.md](TERMINOLOGY.md).\n';
7
9
  const TERMS = '# Terminology\n\n## Terms\n\n| Concept | English | 简体 | 繁體 | Avoid | Meaning | Status | Source |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n';
8
10
  const LOADER = '## Document guidance\n\nFor document drafting and editing, use `write-doc`; for analytical reports, use `write-report`. Read the applicable `WRITING.md` and `TERMINOLOGY.md`. Save future preferences only when explicitly requested; automatic skill selection does not initialize guidance.\nAfter context loss, read and apply the applicable writer skill again before continuing.\n';
11
+ const LANGUAGE_LOADER = '## Language guidance\n\nRead [the local writing guide](<{guide}>), including any explicitly linked inherited writing guide, and follow its shared language rules. At session start, load `plain-language` for replies and read `Agent replies` for reply preferences. Document voice and templates are not chat preferences. After context loss, reload the skill while preserving the session\'s latest explicit style choice; an off command or another chosen reply style must not be reset by file detection.\n';
9
12
  const inside = (root, p) => p === root || (!path.relative(root, p).startsWith('..' + path.sep) && path.relative(root, p) !== '..' && !path.isAbsolute(path.relative(root, p)));
10
13
  const home = fs.realpathSync(os.homedir());
11
14
  const result = { scope: null, start: null, projectBoundary: null, inherited: null, missingInputs: [], files: [], errors: [] };
@@ -33,12 +36,32 @@ function inspect(p, bounded = false) {
33
36
  return { real, bytes, link: lst.isSymbolicLink(), dev: stat.dev, ino: stat.ino, nlink: stat.nlink };
34
37
  }
35
38
  const sameFile = (a, b) => a && b && a.dev === b.dev && a.ino === b.ino;
39
+ // Only active prose can configure a loader; an open block also makes appending unsafe.
40
+ function markdown(text) {
41
+ let fence = null, comment = false; const active = [];
42
+ for (const line of text.split(/\r?\n/)) {
43
+ if (fence) {
44
+ const close = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
45
+ if (close && close[1][0] === fence[0] && close[1].length >= fence.length) fence = null;
46
+ continue;
47
+ }
48
+ let visible = '', rest = line;
49
+ while (rest) {
50
+ if (comment) { const end = rest.indexOf('-->'); if (end < 0) break; rest = rest.slice(end + 3); comment = false; }
51
+ else { const start = rest.indexOf('<!--'); if (start < 0) { visible += rest; break; } visible += rest.slice(0, start); rest = rest.slice(start + 4); comment = true; }
52
+ }
53
+ const open = visible.match(/^ {0,3}(`{3,}|~{3,})/);
54
+ if (open) fence = open[1]; else active.push(visible);
55
+ }
56
+ return { text: active.join('\n'), open: !!fence || comment };
57
+ }
36
58
  function hasLoader(text) {
59
+ text = markdown(text).text;
37
60
  return text.includes(LOADER.trim()) || /for document drafting and editing, use `?write-doc`?; for analytical reports, use `?write-report`?\.\s*read the applicable `?WRITING\.md`? and `?TERMINOLOGY\.md`?\.\s*save future preferences only when explicitly requested; automatic skill selection does not initialize guidance\./i.test(text);
38
61
  }
39
62
  function checkConflict(text, file) {
40
63
  // Deliberately bounded: catch direct negations, not arbitrary natural-language policy.
41
- if (/(?:\b(?:do not|don't|never|must not|cannot|can't)\s+(?:(?:ever|automatically)\s+)?(?:use|invoke|run|read|load|follow|consult|import|initialize|create)\b[^.\n]*(?:write-doc|write-report|WRITING\.md|TERMINOLOGY\.md|AGENTS\.md|CLAUDE\.md)|(?:explicit|automatic)[^.\n]*(?:invocations?|selection)[^.\n]*(?:disabled|prohibited))/i.test(text)) fail('Conflicting document guidance', file);
64
+ if (/(?:\b(?:do not|don't|never|must not|cannot|can't)\s+(?:(?:ever|automatically)\s+)?(?:use|invoke|run|read|load|follow|consult|import|initialize|create)\b[^.\n]*(?:plain-language|write-doc|write-report|WRITING\.md|TERMINOLOGY\.md|AGENTS\.md|CLAUDE\.md)|(?:explicit|automatic)[^.\n]*(?:invocations?|selection)[^.\n]*(?:disabled|prohibited))/i.test(markdown(text).text)) fail('Conflicting document guidance', file);
42
65
  }
43
66
  // Bounded inline Markdown destinations: angle destinations may contain spaces; bare
44
67
  // destinations may have a quoted title. This is not a full CommonMark parser.
@@ -51,6 +74,7 @@ function destination(raw, file) {
51
74
  return ref;
52
75
  }
53
76
  function loadsAgents(text, file, expected, agent) {
77
+ text = markdown(text).text;
54
78
  function validate(ref) {
55
79
  const target = ref && path.resolve(path.dirname(file), ref);
56
80
  const linked = target && inspect(target);
@@ -111,7 +135,7 @@ function parse() {
111
135
  if (fs.existsSync(path.join(d, '.git'))) { boundary = d; break; }
112
136
  if (d === home || d === path.dirname(d)) break;
113
137
  }
114
- scope = explicit ? fs.realpathSync(path.resolve(explicit)) : boundary || start;
138
+ scope = explicit ? fs.realpathSync(path.resolve(explicit)) : start;
115
139
  if (!fs.statSync(scope).isDirectory() || !inside(scope, start)) fail('Scope must contain start', scope);
116
140
  if (boundary && !inside(boundary, scope)) fail('Scope must be within the project boundary', scope);
117
141
  if (inside(scope, home)) fail('Home and its ancestors are not authorized scopes', scope);
@@ -161,26 +185,40 @@ function main() {
161
185
  }
162
186
  const plan = [];
163
187
  function record(p, action, content, item = entries.get(p)) {
188
+ if (action === 'append' && markdown(item.bytes.toString('utf8')).open) fail('Unclosed Markdown block prevents active guidance append', p);
164
189
  result.files.push({ path: p, status: action === 'none' ? 'already configured' : action === 'append' ? 'updated' : 'created' });
165
190
  if (action !== 'none') plan.push({ p, action, content, item });
166
191
  }
167
- record(wp, entries.get(wp) ? 'none' : 'create', WRITING);
192
+ const writing = entries.get(wp);
193
+ const writingText = writing?.bytes.toString('utf8') || '';
194
+ const activeWriting = markdown(writingText).text;
195
+ if (/## Shared language rules\b/.test(activeWriting) && !activeWriting.includes('plain-language/references/language.md')) fail('Conflicting shared language rules; preserve local policy', wp);
196
+ const inherited = guide && !localGuide
197
+ ? `## Inherited writing guidance\n\nRead [the inherited writing guide](<${path.relative(dir, guide.path).split(path.sep).join('/')}>) before this guide; preserve its rules unless a local rule explicitly overrides them.\n\n` : '';
198
+ const needsLanguage = !activeWriting.includes('plain-language/references/language.md');
199
+ if (writing && needsLanguage && /(?:do not|never)\s+(?:change|edit|modify)\s+(?:existing\s+)?`?WRITING\.md/i.test(entries.get(ap)?.bytes.toString('utf8') || '')) fail('Existing policy prohibits updating WRITING.md', wp);
200
+ const writingNl = writingText.includes('\r\n') ? '\r\n' : '\n';
201
+ const languageAppend = (writingText.endsWith('\n') ? writingNl : writingNl + writingNl) + LANGUAGE.replaceAll('\n', writingNl);
202
+ record(wp, writing ? needsLanguage ? 'append' : 'none' : 'create', writing ? languageAppend : WRITING.replace('# Writing guide\n\n', '# Writing guide\n\n' + inherited));
168
203
  record(tp, existingTerm ? 'none' : 'create', TERMS);
169
204
  const agent = entries.get(ap), claude = entries.get(cp);
170
205
  const agentText = agent?.bytes.toString('utf8') || '';
171
206
  checkConflict(agentText, ap);
172
- const agentConfigured = hasLoader(agentText);
173
- function appendText(text) { const nl = text.includes('\r\n') ? '\r\n' : '\n'; return (text && !text.endsWith('\n') ? nl : '') + (text ? nl : '') + LOADER.replaceAll('\n', nl); }
174
- record(ap, agentConfigured ? 'none' : agent ? 'append' : 'create', agent ? appendText(agentText) : LOADER);
207
+ const languageLoader = file => LANGUAGE_LOADER.replace('{guide}', path.relative(path.dirname(file), wp).split(path.sep).join('/'));
208
+ const languageConfigured = (text, file) => markdown(text).text.includes(languageLoader(file).trim());
209
+ const agentFile = agent?.real || ap;
210
+ const agentConfigured = hasLoader(agentText) && languageConfigured(agentText, agentFile);
211
+ function appendText(text, file) { const nl = text.includes('\r\n') ? '\r\n' : '\n'; const loaders = (hasLoader(text) ? '' : LOADER) + (languageConfigured(text, file) ? '' : '\n' + languageLoader(file)); return (text && !text.endsWith('\n') ? nl : '') + (text ? nl : '') + loaders.replaceAll('\n', nl); }
212
+ record(ap, agentConfigured ? 'none' : agent ? 'append' : 'create', appendText(agentText, agentFile));
175
213
  const same = sameFile(agent, claude);
176
214
  const claudeText = claude?.bytes.toString('utf8') || '';
177
215
  checkConflict(claudeText, cp);
178
216
  const referencesAgents = loadsAgents(claudeText, claude?.real || cp, ap, agent);
179
- const claudeConfigured = same || hasLoader(claudeText) || referencesAgents;
217
+ const claudeConfigured = same || (hasLoader(claudeText) && languageConfigured(claudeText, claude?.real || cp)) || referencesAgents;
180
218
  const plannedGuidance = new Set([wp, tp, ap]);
181
219
  if (agent) validateLinks(ap, agent, plannedGuidance, new Set(), true);
182
220
  if (claude && !same) validateLinks(cp, claude, plannedGuidance, new Set(), true);
183
- record(cp, !claude ? 'symlink' : claudeConfigured ? 'none' : 'append', !claude ? 'AGENTS.md' : appendText(claudeText));
221
+ record(cp, !claude ? 'symlink' : claudeConfigured ? 'none' : 'append', !claude ? 'AGENTS.md' : appendText(claudeText, claude?.real || cp));
184
222
  // Reinspect every target and inherited input before starting writes.
185
223
  for (const [p, old] of entries) {
186
224
  const now = inspect(p, true);
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: plain-language
3
- description: "Session mode: every reply and status line in plain language — lead with the point, everyday words, full sentences, no filler — in English or Chinese, until turned off. Enable by default when the project has an applicable WRITING.md, even without a slash command. Use for /plain-language, 'talk plainly', '说人话', and explicit requests to remember project reply preferences; /plain-language init persists the default and loading instructions. Save reply rules only under Agent replies; route document preferences to distill-writing. Ordinary mode toggles remain session-only. Turn off with '/plain-language off' or 'normal mode'. NOT for writing a document (write-doc) or analytical report (write-report) or reviewing one (editorial-review)."
4
- release-version: 0.50.8
3
+ description: "Session mode: every reply and status line in plain language — lead with the point, everyday words, full sentences, no filler — in English or Chinese, until turned off. Enable by default when the project has an applicable WRITING.md, even without a slash command. Use for /plain-language, 'talk plainly', '说人话', and explicit requests to remember project reply preferences; an actual /plain-language invocation automatically configures the current directory's WRITING.md and loading pointers; init remains an alias. Save reply rules only under Agent replies; route document preferences to distill-writing. Natural-language toggles and off remain session-only. Turn off with '/plain-language off' or 'normal mode'. NOT for writing a document (write-doc) or analytical report (write-report) or reviewing one (editorial-review)."
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Plain language
@@ -14,7 +14,9 @@ reply style (such as caveman) also ends it.
14
14
 
15
15
  At session start, look for an applicable `WRITING.md` from the current working directory:
16
16
 
17
- 1. Walk upward one directory at a time. Use the first `WRITING.md`; do not merge guides.
17
+ 1. Walk upward one directory at a time. Use the first `WRITING.md`; do not implicitly merge
18
+ ancestor guides. If it explicitly links an inherited writing guide, read that guide first
19
+ and apply the local additions afterward.
18
20
  2. Include the nearest ancestor containing `.git` (file or directory), then stop there.
19
21
  Without a `.git` ancestor, stop before the user's home directory or any directory above it.
20
22
  3. Do not search unrelated subdirectories. A candidate must be a readable file. Report an
@@ -31,42 +33,53 @@ or choosing another reply style disables this mode for the rest of the session,
31
33
  file again must not undo that choice. After compaction, recover the session's latest explicit
32
34
  style choice before applying the file-based default.
33
35
 
34
- Keep ordinary on/off choices in session context only; do not edit project files or settings for
35
- them. Only `/plain-language init` (or an explicit request to save the project default) authorizes
36
- the setup below. A new session checks for `WRITING.md` again and does not inherit the previous
36
+ Keep natural-language on/off choices and `/plain-language off` in session context only.
37
+ An actual user `/plain-language` invocation, including no arguments, `init` or
38
+ 「将语言规范保存」, automatically performs the setup below. First read the
39
+ [local setup convention](references/setup.md) in full. Automatic selection, inherited
40
+ loading instructions and quoted commands only read existing guidance. A new session checks for `WRITING.md` again and does not inherit the previous
37
41
  session's off choice. Document deliverables still belong to `write-doc` or their owning writing
38
42
  skill; this mode governs replies and status lines. When a guide applies, read its `Agent replies`
39
43
  section for saved reply preferences. Do not treat its document Voice or templates as chat rules.
40
44
 
41
- When explicitly enabled without an applicable `WRITING.md`, offer once per session:
45
+ When enabled by a natural-language request without an applicable `WRITING.md`, offer once per session:
42
46
  "Use `/plain-language init` to make this the project default." Do not interrupt the task with
43
47
  an approval question, repeat the offer on ordinary replies, or offer it after an off command.
44
48
 
45
- - Invoked with no other request: confirm that the mode is on; include the setup offer when it
46
- applies. Otherwise do not announce the mode; just answer in it.
49
+ - Invoked with no other request: perform local setup, confirm the mode is on and report
50
+ the configured paths briefly. Otherwise continue the task after setup without a mode announcement.
47
51
  - Invoked with `off`: reply in one line that the mode is off, and stop following this page.
48
52
  - Code, commands, file paths, identifiers, error text and commit messages stay exact.
49
53
  - Follow the section for the reply's language; a mixed reply follows both.
50
54
 
51
- ## Persist the project default: `/plain-language init`
55
+ ## Automatic local setup
52
56
 
53
- The command authorizes project setup, not a global preference or a permanent on/off toggle.
57
+ An actual user invocation authorizes this setup. `/plain-language init` remains an alias.
58
+ Follow the shared convention; no extra approval is needed for its bounded writes.
54
59
 
55
- 1. Set the setup scope to the nearest ancestor containing `.git` (file or directory), else
56
- the current working directory. Find the applicable `WRITING.md` with the lookup above.
60
+ 1. Set the setup scope to the current working directory, or the user's explicitly chosen
61
+ directory. Find the applicable `WRITING.md` with the lookup above.
57
62
  A guide outside the setup scope may be read, but does not authorize writes in its directory.
58
63
  Place agent loading instructions beside an in-scope guide, else at the setup root.
59
64
  Resolve all planned write targets before changing any file. Report unreadable files,
60
65
  conflicting policy, broken links, or symlinks escaping the setup scope and stop setup
61
66
  without changing files. Never edit a global agent file.
62
67
 
63
- 2. Keep an existing guide unchanged. If none applies, create `WRITING.md` at the setup root.
68
+ 2. Preserve existing guide content. Add only a missing shared-language reference under
69
+ `## Shared language rules`, following the shared convention. If no in-scope guide exists,
70
+ create `WRITING.md` at the setup root. If an ancestor guide applies, explicitly link it
71
+ under `## Inherited writing guidance` so its rules remain effective.
64
72
  Start with this minimal guide; do not invent a house style or document templates:
65
73
 
66
74
  ```markdown
67
75
  <!-- writing-md: 1 -->
68
76
  # Writing guide
69
77
 
78
+ ## Shared language rules
79
+ - Default: read and apply `plain-language/references/language.md` from the installed
80
+ `plain-language` skill for replies, documents and reports. Keep structures and workflows
81
+ with their owning skills.
82
+
70
83
  ## Agent replies
71
84
  - Default: use the `plain-language` skill for chat replies and status updates. _(user)_
72
85
  - A user-requested style change applies only to the current session. _(user)_
@@ -85,6 +98,8 @@ The command authorizes project setup, not a global preference or a permanent on/
85
98
  ```markdown
86
99
  ## Reply style
87
100
 
101
+ Read [the local writing guide](WRITING.md) and any explicitly linked inherited writing guide.
102
+ Apply its shared language reference to replies, documents and reports.
88
103
  At session start, if an applicable WRITING.md exists, load the `plain-language` skill
89
104
  and enable it for replies and status updates. Read the applicable guide's `Agent replies`
90
105
  section, not its document rules, for saved reply preferences. After compaction, reload the skill and
@@ -92,11 +107,16 @@ The command authorizes project setup, not a global preference or a permanent on/
92
107
  reply style lasts for this session; file detection must not turn it back on.
93
108
  ```
94
109
 
110
+ Resolve that guide link relative to the actual instruction target. For a symlink whose
111
+ target lives in a subdirectory, use the corresponding relative path rather than copying
112
+ the example's `WRITING.md` destination. Only active instructions count as configured;
113
+ report an unclosed comment or code fence before appending.
114
+
95
115
  4. Successful init explicitly enables plain language for this session, even if the user
96
116
  previously turned it off. Ordinary file detection or reloading still cannot override off.
97
117
  Report the paths created, updated, or already configured and any inherited guide used.
98
118
  Running init again should leave already-configured files unchanged. Do not change the
99
- guide's document-writing rules or install skills as part of setup.
119
+ guide's existing document-writing rules or install skills as part of setup.
100
120
 
101
121
  The agent loading instruction makes the file-based default discoverable in future sessions;
102
122
  `WRITING.md` alone is not a runtime hook. This setup assumes `plain-language` is installed.
@@ -118,7 +138,7 @@ requested future scope is unclear, ask once before writing; never assume global
118
138
  `WRITING.md`, marking it `_(user)_`. Use Default unless the user makes it Required or Optional.
119
139
  If no in-scope guide exists, create the minimal guide from init plus that reply rule at the
120
140
  chosen scope root. An inherited guide outside scope remains unchanged; explain that the new local
121
- guide shadows it rather than merging its rules. An equivalent
141
+ guide explicitly links the inherited guide and preserves its rules. An equivalent
122
142
  rule already saved is a no-op. Change an existing user rule only when this request clearly
123
143
  replaces it; report an unclear conflict instead of overwriting it.
124
144
  3. Ensure the reply-style loading pointers from init reach every supported local entrypoint;
@@ -137,40 +157,13 @@ not authorization to save preferences. No save authorizes global edits, installs
137
157
 
138
158
  ## Every reply
139
159
 
140
- - **Lead with the point.** The answer or recommendation first, then the reasons.
141
- - **Cut every word that does no work.** No greeting, no restating the question, no recap
142
- of what you just said.
160
+ Read and apply the [shared language rules](references/language.md) in full when this mode
161
+ activates, including after compaction. They cover English and Chinese sentences, factual
162
+ precision and avoiding defensive statements. They ship with this skill; house-style is optional.
163
+
143
164
  - **Fit the length to the question.** A short question gets a short answer; add detail
144
165
  only when the reader needs it to act.
145
- - **Use the short everyday word.** Explain a needed technical term in a few words the first
146
- time. Never leverage, robust, seamless, holistic, streamline, delve.
147
- - **Name who does what.** "The script deletes the branch", not "the branch is deleted".
148
- - **State findings plainly; hedge only real uncertainty, and say what it depends on.**
149
- - **Write full sentences, not telegraphic notes.** Keep if, when, because and but.
150
- Example: "It is 0 if there were no collections," not "0 when none."
151
- - **Give every range its endpoints and say which are included.**
152
- - **When "and" and "or" meet in one condition, group them.** Give each condition its subject.
153
- - **Make every "it", "this" and "they" point to one obvious noun.**
154
- - **Never add a number, date, condition or cause you do not have,** and never turn "may"
155
- into "will".
156
- - One thought per sentence; most sentences under 25 words.
157
166
  - Between tool calls, write one plain sentence on what you are doing and why, or nothing.
158
167
 
159
- ## 中文回复
160
-
161
- - 先给结论,再给理由;不写问候式开场、宣传口号和空泛形容。
162
- - 写完整的句子,不写电报体。示例:`若窗口内无收款,则为 0`,而不是 `无收款为 0`。
163
- - 区间和阈值写明端点,并写明端点是否包含。
164
- - 并列的条件逐个写全对象。示例:`客户已认证,且客户是个人或商户`,而不是 `客户是个人或商户且已认证`。
165
- - 指代可能不清时,用具体名称替代「该」「其」「此」「上述」「相关」。
166
- - 不用掩盖具体动作的词,改写为实际含义:赋能 → 提供;抓手 → 关键措施;对齐 → 统一、确认一致;拉通 / 打通 → 连接。
167
- - 不用装饰性连接词:值得注意的是、不难看出、综上所述。
168
- - 中文与英文、数字之间加一个半角空格。
169
-
170
- ## When a rule makes a reply worse
171
-
172
- Fix the sentence another way. Never shorten a warning, an irreversible step or an ordered
173
- procedure to save words.
174
-
175
168
  Full guides: [style-en](../house-style/references/style-en.md),
176
169
  [style-zh](../house-style/references/style-zh.md) (from `house-style`, when installed).
@@ -0,0 +1,146 @@
1
+ # Shared language rules
2
+
3
+ Read and apply these rules for replies, documents and reports in English or Chinese.
4
+ This file owns their common language principles. The calling skill owns structure,
5
+ templates, review, delivery and session behavior. Project guidance retains the calling
6
+ skill's precedence; document voice and templates do not become chat preferences.
7
+
8
+ ## Core rules
9
+
10
+ - **Lead with the point.** Give the answer or recommendation, then the reasons.
11
+ - **Cut every word that does no work.** Remove greetings, repeated conclusions and filler.
12
+ - **Use the short everyday word.** Explain necessary technical terms at first use.
13
+ Avoid leverage, robust, seamless, holistic, streamline and delve as filler.
14
+ - **Name who does what.** "The script deletes the branch", not "the branch is deleted".
15
+ - **State findings plainly; hedge only real uncertainty, and say what it depends on.**
16
+ - Remove the entire defensive frame, not just its wording. State the relevant result;
17
+ leave out broader comparisons introduced only to preempt imagined objections.
18
+ - Express actual relationships in ordinary sentences, not invented compound labels or
19
+ unnecessary contrasts. Let the meaning connect sentences and determine the format.
20
+ - **Write full sentences, not telegraphic notes.** Include a subject and a predicate:
21
+ say who or what the sentence concerns and what that subject does, is or experiences.
22
+ Avoid fragments that omit both. Keep if, when, because and but.
23
+ Example: "It is 0 if there were no collections," not "0 when none."
24
+ - **Give every range its endpoints and say which are included.**
25
+ - **When "and" and "or" meet in one condition, group them.** Give each condition its subject.
26
+ - **Make every "it", "this" and "they" point to one obvious noun.**
27
+ - **Never add a number, date, condition or cause you do not have,** and never turn "may"
28
+ into "will". Preserve material conditions, risks and uncertainty.
29
+ - One thought per sentence; most English sentences under 25 words.
30
+ - When a language rule makes a sentence worse, fix the sentence another way. Preserve
31
+ warnings, irreversible steps, ordered procedures and mandated wording.
32
+
33
+ ## Complete sentences
34
+
35
+ In explanatory prose and status updates, write a subject and a predicate, not a cluster of
36
+ nouns or labels. The reader should not have to reconstruct who did what or what changed.
37
+ Write "The tests passed, and I committed the changes," not "Tests green; commit done."
38
+ Use only supported actors and actions; do not invent an owner to complete a sentence.
39
+ Headings, field labels and compact table cells may remain labels. Commands may use an
40
+ understood subject, as in "Open the alert"; keep their action verb and object explicit.
41
+
42
+ 正文和进度说明要有主语和谓语,写清楚谁做什么、什么是什么,或什么处于什么状态。
43
+ 避免主语和谓语同时缺失的名词堆叠或标签串。写「测试已通过,我已提交修改」,
44
+ 不要写「测试全绿,修改提交」。不要为了补主语而编造责任人。标题、字段名和紧凑表格
45
+ 中的标签可以使用短语;操作指令可以省略明确的执行者,但要保留动作和对象。
46
+
47
+ ## Direct statements, not self-defense
48
+
49
+ **Remove the frame, not just the disclaimer.** Decide whether the topic belongs in the
50
+ answer before choosing its wording. A defensive sentence often introduces a broader standard
51
+ or imagined objection the reader did not ask about. Remove that unnecessary topic along with
52
+ the disclaimer. Replacing "only" or "does not mean" with a neutral status sentence does not
53
+ solve the problem if the answer still addresses the same unasked objection.
54
+
55
+ **删除整个自辩框架,而不只是替换防御措辞。** 先判断这件事是否需要说,再决定怎么说。
56
+ 如果一个话题只为预先回应假想质疑而出现,就连同这个话题一起删除;不要把它改写成另一句
57
+ 看似中性的状态说明。直接陈述读者需要的事实、判断或行动,不主动引入无关的更高标准、
58
+ 未被询问的比较或责任辩解。
59
+
60
+ State the fact, judgment or action directly. Remove sentences whose only purpose is to
61
+ defend the author's caution, competence, innocence or motives. Answer an actual question;
62
+ do not anticipate objections nobody raised or justify unasked writing and workflow choices.
63
+
64
+ Keep a qualification when removing it would change the reader's understanding, decision
65
+ or action. Name the specific scope, condition, risk or uncertainty and its consequence.
66
+ If the evidence supports a narrower claim, narrow the claim rather than attaching a
67
+ disclaimer to an overstatement. Keep legal, contractual and user-mandated statements exact.
68
+ Report action status when the reader asks for it or needs it to act.
69
+
70
+ Use this test: would deleting the sentence materially mislead the reader about the facts,
71
+ responsibility or next action? If yes, keep it and make it specific. If it only protects
72
+ the author's image, delete it. Negation itself is not the problem: "a refund request is
73
+ not a completed refund" distinguishes states the reader needs to understand.
74
+
75
+ Examples show form, not facts to invent:
76
+
77
+ | Avoid | Prefer, when supported |
78
+ | --- | --- |
79
+ | This is only a suggestion; the final decision remains yours. | We recommend changing the retry policy because [supported reason]. |
80
+ | This does not mean the entire system is unreliable. | The check covered two interfaces; the other interfaces were not tested. |
81
+ | Independent validation was not required, so its absence does not reduce the analysis's value. | Rules were selected and scored on the same transactions; independent-sample performance has not been tested. |
82
+ | 这不是为了增加流程,而是为了确保安全。 | 权限检查必须在发布前完成。 |
83
+ | 我只是提供一个建议,最终仍由你决定。 | 我建议调整重试策略,理由是[有依据的原因]。 |
84
+ | 这不代表系统存在问题,也不能据此否定整体效果。 | 本次检查覆盖两个接口,其他接口未纳入检查。 |
85
+ | 这只是本地单轮回放通过,不代表六格验收完成。 | 本地单轮回放已通过。 |
86
+
87
+ For a progress update about a local check, report the local result. Omit unasked comparisons
88
+ with broader acceptance, deployment or production readiness; rewriting a disclaimer as two
89
+ status sentences still preserves its defensive frame. Mention broader status when the reader
90
+ asks about it, it is owed by the active task, or it affects the next action. In that case,
91
+ report the known status directly, distinguishing incomplete, failed and unknown. Do not claim
92
+ overall completion from a local pass or omit an outstanding obligation in a completion report.
93
+
94
+ ## Natural wording and flow
95
+
96
+ - Use established terms and precise verbs. Unpack an invented compound label into who does
97
+ what, to which object and under which condition. Keep official names and identifiers exact.
98
+ Technical detail earns its place when it helps this reader understand or act.
99
+ - State the point directly. Use contrasts when the alternatives matter to the question;
100
+ otherwise omit the unasked alternative. "X, not Y" and "This isn't about X; it's about Y"
101
+ are not default ways to emphasize a point.
102
+ - Connect each sentence to the preceding idea. Develop a paragraph through explanation,
103
+ evidence or consequence. Avoid canned transitions, repeated question-and-answer beats,
104
+ decorative metaphors and closing summaries that add no information. Familiar phrases
105
+ such as "Bottom line" or "It's worth noting" do not supply the missing relationship.
106
+ - Use paragraphs for a connected explanation. Use lists for genuinely parallel items or
107
+ steps, and tables for comparisons. Add headings and nesting only when they help readers
108
+ navigate; a short answer does not need a miniature report. Preserve required templates.
109
+ - Match the reader, purpose and supplied voice. A rewrite should not impose a generic
110
+ promotional, romantic or clinical tone. When the user identifies a wording problem,
111
+ correct the affected passage rather than substituting an apology or analysis for the edit.
112
+
113
+ 用正常句子写清实际关系,不用自造标签压缩意思,也不为强调观点而制造对比。
114
+ 例如,写「检查当前提交是否通过测试」,不要把动作包装成「精确提交验证闭环」。
115
+ 句子之间要承接意思,段落要推进解释、证据或结论,不能只靠「值得注意的是」等套话连接。
116
+ 连贯的解释使用段落;并列事项、操作步骤和比较再分别使用列表或表格。改写应保留原文的
117
+ 用途和语气;用户指出问题后,应实际修改文字,不能只分析问题、道歉或承诺。
118
+
119
+ ## Chinese sentences
120
+
121
+ - 先给结论,再给理由;不写问候式开场、宣传口号和空泛形容。
122
+ - 写完整的句子,不写电报体。正文要有主语和谓语,避免两者同时缺失。
123
+ 示例:`若窗口内无收款,则该指标的值为 0`,而不是 `无收款为 0`。
124
+ - 区间和阈值写明端点,并写明端点是否包含。
125
+ - 并列的条件逐个写全对象。示例:`客户已认证,且客户是个人或商户`,而不是 `客户是个人或商户且已认证`。
126
+ - 指代可能不清时,用具体名称替代「该」「其」「此」「上述」「相关」。
127
+ - 不用掩盖具体动作的词,改写为实际含义:赋能 → 提供;抓手 → 关键措施;对齐 → 统一、确认一致;拉通 / 打通 → 连接。
128
+ - 不用装饰性连接词:值得注意的是、不难看出、综上所述。
129
+ - 中文与英文、数字之间加一个半角空格。
130
+ - 直接写事实、判断和行动。删除只为作者自辩、泛泛免责或预先反驳假想质疑的句子。
131
+ 保留会改变读者理解、决定或行动的具体限制。结论超出证据时,缩小结论。
132
+ - 去掉自辩框架,不只是换掉「只是」「不代表」。汇报本地检查时,直接写检查结果;
133
+ 无需主动引入整体验收、部署或生产可用性等更大话题。仅在读者询问、当前任务要求交代,
134
+ 或影响下一步行动时说明这些状态。
135
+
136
+ ## Sources
137
+
138
+ - [OpenAI: Using GPT-6, Personality and writing style](https://developers.openai.com/api/docs/guides/latest-model#personality-and-writing-style).
139
+ The guidance describes recurring phrases, formatting, jargon, invented compound labels
140
+ and unprompted contrasts. These are useful editing targets, not a measured frequency of
141
+ defects across every GPT-6 model or language.
142
+ - [OpenAI Developer Community: writing feedback and comparisons](https://community.openai.com/t/problem-with-gpt-6-request-for-assistance/1414016/3).
143
+ Individual reports describe imposed tone, mechanical dialogue and repeated problems after
144
+ critique. They motivate preserving voice and making actual edits, not a universal claim
145
+ about fiction quality. The Chinese examples above illustrate our rules; they are not
146
+ quotations from measured model outputs.
@@ -0,0 +1,44 @@
1
+ # Local writing setup convention
2
+
3
+ An actual user slash invocation of `/plain-language`, `/write-doc` or `/write-report`
4
+ authorizes local setup as part of normal use, including invocation without arguments,
5
+ `init`, fast mode and 「将语言规范保存」. Complete setup before continuing the requested
6
+ work; no separate save request or confirmation is needed.
7
+
8
+ Automatic skill selection, another workflow calling the skill, reading a skill, a quoted
9
+ command and natural-language session toggles do not authorize setup. `/plain-language off`
10
+ and "normal mode" only change the current session. An explicitly session-only request
11
+ also skips setup. After context loss, do not treat a reloaded skill as a fresh invocation.
12
+
13
+ ## Scope and files
14
+
15
+ Use the current working directory unless the user explicitly chooses another setup
16
+ directory. Do not infer setup scope from an input/output path or move writes to the Git
17
+ root. Never write home-level or global guidance. Validate all targets before writing;
18
+ preserve the calling skill's checks for unreadable files, links, conflicts and permissions.
19
+
20
+ - In that directory, create `WRITING.md` if missing. Preserve an existing guide and add
21
+ only a missing shared-language reference. Store a reference to
22
+ `plain-language/references/language.md` in the installed `plain-language` skill, not a
23
+ copy or machine-specific installation path. It applies to replies, documents and reports;
24
+ each calling skill retains its structure and workflow. Keep local preferences separate.
25
+ - If the new local guide would shadow an inherited guide, add an explicit relative link
26
+ under `## Inherited writing guidance`. Instruct readers to read that guide first and
27
+ apply local additions afterward. Do not copy, modify or silently discard the parent guide.
28
+ Only explicit inheritance links are followed; do not implicitly merge ancestor guides.
29
+ - Add a loading pointer to local `AGENTS.md`. It must direct future sessions to read local
30
+ `WRITING.md`, its explicit inheritance links and the shared language reference. For chat,
31
+ load `plain-language` and read `Agent replies`; document voice and templates do not become
32
+ chat rules. Preserve an explicit session off choice after reload or file detection.
33
+ Resolve the guide link relative to each actual instruction-file target, including
34
+ symlink targets in subdirectories. Count only active instructions, not examples inside
35
+ comments or code fences; block appends into an unclosed comment or fence.
36
+ - Ensure existing `CLAUDE.md` entrypoints reach the loader. Preserve valid in-scope links
37
+ and unrelated instructions. A missing `CLAUDE.md` may be a relative link to `AGENTS.md`.
38
+ - Writers also initialize `TERMINOLOGY.md` under their existing contract. Plain-language
39
+ setup alone does not create terminology or templates, learn a style or save task details.
40
+
41
+ An equivalent active reference or loader is already configured. Preserve local language
42
+ rules, reply preferences and manual edits; report conflicting policy instead of overwriting
43
+ it. Repeated setup must leave configured files unchanged. Report created or updated paths
44
+ briefly, then resume the user's task. A setup failure must not be reported as success.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: polish-cn
3
3
  description: "Polish the Chinese wording of a finished document or report, with a script proving every number, date, identifier, link and protected term is unchanged; prefers a Chinese model and records which ran. Use for '中文润色' or as a report skill's last step. NOT for cutting or restructuring content (editorial-review) or translating (write-doc or write-report)."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Polish Chinese
@@ -2,7 +2,7 @@
2
2
  name: reg-parser
3
3
  version: 1.1.0
4
4
  description: "Parse regulatory/scheme documents into structured outputs: convert a regulation (AML, VARS, PCI-DSS, KYC, GDPR) into an audit-ready compliance checklist, or trace contract clauses to a mandate source. Suggest proactively when a regulation PDF accompanies a contract review or compliance task. NOT general summarization (doc-to-md), writing a gap-analysis report (write-report), or writing a policy from the checklist (write-doc)."
5
- release-version: 0.50.8
5
+ release-version: 0.50.9
6
6
  ---
7
7
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
8
  # reg-parser
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: terminology
3
3
  description: "Build and keep a project's TERMINOLOGY.md: the preferred term per concept in English, 简体 and 繁體, and the terms to avoid. Use to set it up from the project's documents, when the user settles or corrects a term, or when another writing skill needs the format. NOT for writing documents (write-doc) or analytical reports (write-report) or the code domain model (domain-modeling)."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Terminology
@@ -1,13 +1,16 @@
1
1
  ---
2
2
  name: write-doc
3
3
  description: "Write or edit documents that define or propose something: BRD, PRD, technical spec, integration guide, proposal, policy or risk procedure; English, Chinese or bilingual. Use automatically for drafting or revising these documents. Markdown by default; export when requested. NOT for analytical reports or writing up findings (write-report), ordinary chat replies (plain-language), learning style or saving preferences alone (distill-writing), performing an audit (compliance-audit), or WeChat articles (wechat-article-writer)."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Write a document
8
8
 
9
+ Read and apply the [shared language rules](../plain-language/references/language.md)
10
+ in full before drafting or editing, including when local guidance supplies the style.
11
+
9
12
  Write a document that defines requirements, proposes a choice, or tells its reader what to do.
10
- An explicit user `/write-doc` invocation first follows
13
+ An explicit user `/write-doc` invocation automatically configures the current directory via
11
14
  [local initialization](../house-style/references/initialization.md) to persist `WRITING.md`,
12
15
  `TERMINOLOGY.md` and their loading pointers. Automatic selection does not initialize guidance.
13
16
  Read and follow the [shared drafting and editing workflow](../house-style/references/document-workflow.md)
@@ -1,11 +1,14 @@
1
1
  ---
2
2
  name: write-report
3
3
  description: "Write or edit analytical reports from data, research, analysis or findings: payment, fraud, operational, performance, research, gap-analysis, audit, external assessment, management and Visa VARS reports. Use whenever asked to report results, write up findings, or turn analysis into a report, even without naming this skill. English, Chinese or bilingual; Markdown by default, export when requested. NOT for defining requirements, policies or proposals (write-doc), performing the underlying domain analysis or audit, chat-only answers (plain-language), or learning house style (distill-writing)."
4
- release-version: 0.50.8
4
+ release-version: 0.50.9
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Write an analytical report
8
8
 
9
+ Read and apply the [shared language rules](../plain-language/references/language.md)
10
+ in full before drafting or editing, including when local guidance supplies the style.
11
+
9
12
  **Every analytical section must make a supported point. Its evidence should establish that
10
13
  point, and its limitations should explain what would change the reader's interpretation or action.**
11
14
 
@@ -13,7 +16,7 @@ Explain what was examined, what was found, how strongly the sources support it,
13
16
  reader should decide or do. Recommendations may follow findings; they do not turn a report
14
17
  into a proposal or authorize changing the underlying analysis.
15
18
 
16
- An explicit user `/write-report` invocation first follows
19
+ An explicit user `/write-report` invocation automatically configures the current directory via
17
20
  [local initialization](../house-style/references/initialization.md) to persist `WRITING.md`,
18
21
  `TERMINOLOGY.md` and their loading pointers. Automatic selection or a domain call does not
19
22
  initialize guidance. This skill coordinates drafting, `editorial-review`, fixes, optional