@1aboveio/core-skills 0.1.4 → 0.1.5

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.4",
3
+ "version": "0.1.5",
4
4
  "description": "Shared writing and document foundation: house style, plain-language replies, editorial review, Chinese polish, terminology, write-doc, 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": "62a4265c57d6f35b5a4f428e5b6e3e6f9953269b85a53f47ebd71cee9388aec7"
30
+ "digest": "8952bc1d2ca7fcf2ee94b9981cfa358848c83fbdfb75af2cc635a5ebf09bad25"
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 into the project's WRITING.md and writing/templates/, with evidence per rule, conflicts surfaced and manual edits kept. Use when given reference documents to learn from, or to set up or refresh the house style. NOT for writing a document (write-doc)."
4
- release-version: 0.41.0
4
+ release-version: 0.42.0
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.41.0
4
+ release-version: 0.42.0
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 and the report skills. NOT for Chinese wording (polish-cn) or code review (better-review)."
4
- release-version: 0.41.0
4
+ release-version: 0.42.0
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.41.0
6
+ release-version: 0.42.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # House style
@@ -47,15 +47,26 @@ the table: "Owners and dates are to be agreed by `<who>`." Never write `[TBD: ow
47
47
 
48
48
  - **Headings**: sentence case, informative ("Disputes double after the price change", not
49
49
  "Analysis"). `#` once for the title; do not skip levels, unless WRITING.md or the template
50
- records a house pattern that does (house evidence beats this default).
51
- - **Paragraphs**: two to five sentences. One line per paragraph in the source file; no hard wraps
52
- inside a paragraph unless the project's files already wrap.
53
- - **Lists**: only for parallel items or steps. Numbered for sequences, bullets otherwise. Not for
54
- reasoning that needs "because" and "so".
50
+ records a house pattern that does (house evidence beats this default). In longer content,
51
+ prefer a standalone heading for each section or numbered topic, with the body below it.
52
+ An inline heading can suit a compact note; do not turn every paragraph into a labeled item.
53
+ - **Paragraphs**: use prose for explanation and connected actions. Break at a change of focus,
54
+ not at a fixed sentence count. A paragraph may be one sentence; do not pad it to meet a quota
55
+ or force an entire topic into one long paragraph. One line per paragraph in the source file;
56
+ no hard wraps inside a paragraph unless the project's files already wrap.
57
+ - **Lists**: use them when readers need to identify distinct rules, conditions, options or steps
58
+ separately. Numbered for sequences, bullets otherwise. Keep reasoning and connected actions
59
+ in prose. Introduce a list with a complete sentence and put shared context or follow-up
60
+ explanation outside it. A section may mix prose and a list.
61
+ - **Layout follows meaning**: choose paragraph and list breaks for the content, not for visual
62
+ symmetry. Do not add, split or merge points just to give every section the same count or
63
+ layout. Repeated formats are useful for genuinely comparable items and checklists. Preserve
64
+ the user's chosen structure during an edit unless the requested change requires otherwise.
55
65
  - **Tables**: when three or more items share the same attributes. Every column has a header; no
56
66
  empty cells (write `n/a` or `TBD`).
57
67
  - **Emphasis**: bold for the few words a skimming reader must see; no bold sentences in a row, no
58
- italics for emphasis, no ALL CAPS.
68
+ italics for emphasis, no ALL CAPS. Avoid a bold label on every paragraph or bullet when the
69
+ text already makes the distinction clear.
59
70
  - **Code**: field names, endpoints, commands, file names and config keys in code font, exactly as
60
71
  the system spells them.
61
72
  - **Links and citations**: link the descriptive words, not "here". Cite a source after the claim it
@@ -64,3 +75,18 @@ the table: "Owners and dates are to be agreed by `<who>`." Never write `[TBD: ow
64
75
  than four steps or actors in mind. Every diagram has a sentence saying what it shows.
65
76
  - **Callouts**: a blockquote starting `**Note:**` or `**Warning:**` (`**注意:**`, `**警告:**`),
66
77
  only for an aside that would derail the paragraph.
78
+
79
+ ### Example: prose, a list, then prose
80
+
81
+ Keep the purpose and follow-up in paragraphs; list only the items readers need to distinguish:
82
+
83
+ > **Validate the alert rules**
84
+ >
85
+ > Test the following patterns before enabling automatic holds.
86
+ >
87
+ > - One payer sends repeated payments of the same amount.
88
+ > - Several customers pay the same beneficiary.
89
+ >
90
+ > Review false positives before deciding which alerts should block payouts.
91
+
92
+ A neighboring section may need only one paragraph. Do not give it a list to match this one.
@@ -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. Use for /plain-language, \"plain language mode\", \"talk plainly\", \"说人话\", or when the user's instructions say to use plain-language. Turn off with \"/plain-language off\" or \"normal mode\". NOT for writing a document (write-doc) or reviewing one (editorial-review)."
4
- release-version: 0.41.0
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 /plain-language init to persist that project default and its agent loading instructions. Use for /plain-language, \"plain language mode\", \"talk plainly\", \"说人话\", or when the user's instructions say to use plain-language. Turn off with \"/plain-language off\" or \"normal mode\". NOT for writing a document (write-doc) or reviewing one (editorial-review)."
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Plain language
@@ -10,12 +10,95 @@ Write every reply in this style for the rest of the session, including status li
10
10
  summaries, until the user says `/plain-language off` or "normal mode". A switch to another
11
11
  reply style (such as caveman) also ends it.
12
12
 
13
- - Invoked with no other request: reply in one line that the mode is on. Otherwise do not
14
- mention the mode; just answer in it.
13
+ ## Activation and session state
14
+
15
+ At session start, look for an applicable `WRITING.md` from the current working directory:
16
+
17
+ 1. Walk upward one directory at a time. Use the first `WRITING.md`; do not merge guides.
18
+ 2. Include the nearest ancestor containing `.git` (file or directory), then stop there.
19
+ Without a `.git` ancestor, stop before the user's home directory or any directory above it.
20
+ 3. Do not search unrelated subdirectories. A candidate must be a readable file. Report an
21
+ unreadable, invalid, or uninspectable candidate instead of treating it as absent.
22
+
23
+ Its presence enables this mode for the session; no special section or opt-in text is needed.
24
+ With no applicable file, keep explicit activation as before; absence alone does not enable
25
+ or disable the mode. These lookup rules are included here so a standalone installation works;
26
+ `house-style` is not required. Do not initialize over an unreadable guide.
27
+
28
+ An explicit user choice wins over automatic activation. `/plain-language off`, "normal mode",
29
+ or choosing another reply style disables this mode for the rest of the session, even when
30
+ `WRITING.md` exists. Enable it again only if the user asks. Reloading this skill or finding the
31
+ file again must not undo that choice. After compaction, recover the session's latest explicit
32
+ style choice before applying the file-based default.
33
+
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
37
+ session's off choice. Document deliverables still belong to `write-doc` or their owning writing
38
+ skill; this mode governs replies and status lines.
39
+
40
+ When explicitly enabled without an applicable `WRITING.md`, offer once per session:
41
+ "Use `/plain-language init` to make this the project default." Do not interrupt the task with
42
+ an approval question, repeat the offer on ordinary replies, or offer it after an off command.
43
+
44
+ - Invoked with no other request: confirm that the mode is on; include the setup offer when it
45
+ applies. Otherwise do not announce the mode; just answer in it.
15
46
  - Invoked with `off`: reply in one line that the mode is off, and stop following this page.
16
47
  - Code, commands, file paths, identifiers, error text and commit messages stay exact.
17
48
  - Follow the section for the reply's language; a mixed reply follows both.
18
49
 
50
+ ## Persist the project default: `/plain-language init`
51
+
52
+ The command authorizes project setup, not a global preference or a permanent on/off toggle.
53
+
54
+ 1. Set the setup scope to the nearest ancestor containing `.git` (file or directory), else
55
+ the current working directory. Find the applicable `WRITING.md` with the lookup above.
56
+ A guide outside the setup scope may be read, but does not authorize writes in its directory.
57
+ Place agent loading instructions beside an in-scope guide, else at the setup root.
58
+ Resolve all planned write targets before changing any file. Report unreadable files,
59
+ conflicting policy, broken links, or symlinks escaping the setup scope and stop setup
60
+ without changing files. Never edit a global agent file.
61
+
62
+ 2. Keep an existing guide unchanged. If none applies, create `WRITING.md` at the setup root.
63
+ Start with this minimal guide; do not invent a house style or document templates:
64
+
65
+ ```markdown
66
+ <!-- writing-md: 1 -->
67
+ # Writing guide
68
+
69
+ ## Agent replies
70
+ - Default: use the `plain-language` skill for chat replies and status updates. _(user)_
71
+ - A user-requested style change applies only to the current session. _(user)_
72
+ ```
73
+
74
+ 3. At the chosen loading-instruction directory, ensure `AGENTS.md` and every existing
75
+ `CLAUDE.md` entrypoint can reach the instruction below. Create `AGENTS.md` if missing.
76
+ For a regular file or a valid in-scope symlink, inspect the resolved file and add the
77
+ instruction unless it already contains an equivalent loader or loads a configured
78
+ `AGENTS.md`. This includes symlinks to distinct instruction files, not only a shared
79
+ `AGENTS.md` target. If `CLAUDE.md` is missing, create a relative symlink to `AGENTS.md`.
80
+ Preserve unrelated text and existing valid links. Edit a shared target only once, and
81
+ resolve links relative to each instruction file. Do not claim setup is complete while
82
+ an entrypoint is unresolved.
83
+
84
+ ```markdown
85
+ ## Reply style
86
+
87
+ At session start, if an applicable WRITING.md exists, load the `plain-language` skill
88
+ and enable it for replies and status updates. After compaction, reload the skill and
89
+ preserve the session's latest explicit style choice. An off command or another chosen
90
+ reply style lasts for this session; file detection must not turn it back on.
91
+ ```
92
+
93
+ 4. Successful init explicitly enables plain language for this session, even if the user
94
+ previously turned it off. Ordinary file detection or reloading still cannot override off.
95
+ Report the paths created, updated, or already configured and any inherited guide used.
96
+ Running init again should leave already-configured files unchanged. Do not change the
97
+ guide's document-writing rules or install skills as part of setup.
98
+
99
+ The agent loading instruction makes the file-based default discoverable in future sessions;
100
+ `WRITING.md` alone is not a runtime hook. This setup assumes `plain-language` is installed.
101
+
19
102
  ## Every reply
20
103
 
21
104
  - **Lead with the point.** The answer or recommendation first, then the reasons.
@@ -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)."
4
- release-version: 0.41.0
4
+ release-version: 0.42.0
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), or writing the gap analysis or policy from the checklist (write-doc)."
5
- release-version: 0.41.0
5
+ release-version: 0.42.0
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 the code domain model (domain-modeling)."
4
- release-version: 0.41.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Terminology
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: write-doc
3
3
  description: "Write or edit a Markdown document in the project's house style, using the nearest WRITING.md and a document template (BRD, PRD, gap analysis, technical spec, integration guide, commercial proposal, compliance policy, risk operations procedure, or the project's own); English, Chinese or bilingual. NOT for learning a style from samples (distill-writing), audit reports from findings (report-writing), or WeChat articles (wechat-article-writer)."
4
- release-version: 0.41.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Write a document