@1aboveio/skills 1.0.1 → 1.0.3

package/skills/core/plain-language/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: plain-language
+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)."
+release-version: 0.40.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Plain language
+
+Write every reply in this style for the rest of the session, including status lines and
+summaries, until the user says `/plain-language off` or "normal mode". A switch to another
+reply style (such as caveman) also ends it.
+
+- Invoked with no other request: reply in one line that the mode is on. Otherwise do not
+  mention the mode; just answer in it.
+- Invoked with `off`: reply in one line that the mode is off, and stop following this page.
+- Code, commands, file paths, identifiers, error text and commit messages stay exact.
+- Follow the section for the reply's language; a mixed reply follows both.
+
+## Every reply
+
+- **Lead with the point.** The answer or recommendation first, then the reasons.
+- **Cut every word that does no work.** No greeting, no restating the question, no recap
+  of what you just said.
+- **Fit the length to the question.** A short question gets a short answer; add detail
+  only when the reader needs it to act.
+- **Use the short everyday word.** Explain a needed technical term in a few words the first
+  time. Never leverage, robust, seamless, holistic, streamline, delve.
+- **Name who does what.** "The script deletes the branch", not "the branch is deleted".
+- **State findings plainly; hedge only real uncertainty, and say what it depends on.**
+- **Write full sentences, not telegraphic notes.** Keep if, when, because and but.
+  Example: "It is 0 if there were no collections," not "0 when none."
+- **Give every range its endpoints and say which are included.**
+- **When "and" and "or" meet in one condition, group them.** Give each condition its subject.
+- **Make every "it", "this" and "they" point to one obvious noun.**
+- **Never add a number, date, condition or cause you do not have,** and never turn "may"
+  into "will".
+- One thought per sentence; most sentences under 25 words.
+- Between tool calls, write one plain sentence on what you are doing and why, or nothing.
+
+## 中文回复
+
+- 先给结论，再给理由；不写问候式开场、宣传口号和空泛形容。
+- 写完整的句子，不写电报体。示例：`若窗口内无收款，则为 0`，而不是 `无收款为 0`。
+- 区间和阈值写明端点，并写明端点是否包含。
+- 并列的条件逐个写全对象。示例：`客户已认证，且客户是个人或商户`，而不是 `客户是个人或商户且已认证`。
+- 指代可能不清时，用具体名称替代「该」「其」「此」「上述」「相关」。
+- 不用掩盖具体动作的词，改写为实际含义：赋能 → 提供；抓手 → 关键措施；对齐 → 统一、确认一致；拉通 / 打通 → 连接。
+- 不用装饰性连接词：值得注意的是、不难看出、综上所述。
+- 中文与英文、数字之间加一个半角空格。
+
+## When a rule makes a reply worse
+
+Fix the sentence another way. Never shorten a warning, an irreversible step or an ordered
+procedure to save words.
+
+Full guides: [style-en](../house-style/references/style-en.md),
+[style-zh](../house-style/references/style-zh.md) (from `house-style`, when installed).

package/skills/core/plain-language/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/core/polish-cn/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: polish-cn
 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)."
-release-version: 0.38.0
+release-version: 0.40.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Polish Chinese

package/skills/core/reg-parser/SKILL.md

@@ -2,7 +2,7 @@
 name: reg-parser
 version: 1.1.0
 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)."
-release-version: 0.38.0
+release-version: 0.40.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # reg-parser

package/skills/core/terminology/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: terminology
 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)."
-release-version: 0.38.0
+release-version: 0.40.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Terminology

package/skills/core/write-doc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: write-doc
 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)."
-release-version: 0.38.0
+release-version: 0.40.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Write a document

package/skills/engineering/better-review/SKILL.md

@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/better-review). Single-agent adversarial rev
 disable-model-invocation: true
 dependencies:
   - engineering-runtime
-release-version: 0.38.0
+release-version: 0.40.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Better Review

package/skills/engineering/contributing/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/engineering/contributing/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: contributing
+description: "The conventions a repo's CONTRIBUTING.md holds, starting with tracker routing: which tracker an issue belongs in (GitHub for engineering, Linear for product), duplicate search, and linking back to the source requirement. Use before creating any issue, spec, epic, ticket or sub-issue on GitHub or Linear, including inside /to-spec, /to-tickets and /triage, and whenever work that started from a Linear issue turns into engineering work. Also writes the rules as the Issue tracking section of the repo's CONTRIBUTING.md. NOT for delivering a PR (github-flow) or splitting work into slices (to-tickets)."
+release-version: 0.40.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Contributing
+
+Rules every engineering skill follows, whatever skill or harness is running, kept as sections of the
+repo's `CONTRIBUTING.md`. Each rule is the authority; another skill's "publish to the configured
+tracker" means the tracker these rules pick.
+
+## First use in a repo
+
+Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file
+from, never your CWD. On the first trigger in a repo, write the `## Issue tracking` section into its
+`CONTRIBUTING.md`, creating the file when it is missing:
+
+```sh
+node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <repo-root> --if-missing --write \
+  [--linear-project "<Linear project>"]... [--github-repo <owner/name>]
+```
+
+- **Pass every Linear project whose resources link to this repo.** Example: the `Checkout Risk`
+  project lists `https://github.com/acme/widgets`, so pass `--linear-project "Checkout Risk"`.
+- **Pass `--github-repo` only when `origin` is not the GitHub repo.** Example: exit 2 with
+  `no GitHub origin remote` means pass it.
+- **`--if-missing` never touches an existing section.** To rewrite it, run without `--if-missing`.
+- **`AGENTS.md` indexes `CONTRIBUTING.md`.** The script adds a `## Contributing` pointer unless
+  `AGENTS.md` already names `CONTRIBUTING.md`, creates a missing `AGENTS.md`, and creates a missing
+  `CLAUDE.md` as a symlink to `AGENTS.md`, even when the section already exists.
+- Report each file's result line; commit with the change you are making, or leave it for the user
+  when you make no other change.
+
+## Tracker routing
+
+| Work item | Tracker |
+|---|---|
+| Product goals, business requirements, priorities, milestones | Linear |
+| Consulting engagements, reports, research deliverables | Linear |
+| Engineering specs and implementation epics | GitHub |
+| Implementation tickets, technical investigations, refactors, engineering bugs | GitHub |
+| Delivery progress for stakeholders | A summary in Linear that links to GitHub |
+
+Before you create an issue:
+
+1. **Classify the work; the tracker follows the work, not where the request came from.** Example:
+   `/to-spec` run on a conversation about DEV-123 publishes a GitHub issue.
+2. **Resolve the GitHub repo in this order: the repo's `CONTRIBUTING.md` Issue tracking section, the
+   GitHub links in the source Linear project's resources, then ask the user. Never fall back to
+   Linear.** Example: a project linking two repos gets the repo the work changes; a project linking
+   none gets a question, not a Linear ticket.
+3. **Search before you create.** Example: `gh issue list --repo <owner/name> --state all --search
+   "<keywords>"`; reuse or comment on a match.
+4. **A Linear issue is a source reference, never a parent for implementation tickets.** Example: put
+   `Source: <Linear URL>` in the GitHub epic body and file the tickets as GitHub sub-issues of the
+   epic.
+5. **Link back once per epic.** Example: add the GitHub epic URL to the Linear requirement as a
+   link; never copy the GitHub tickets into Linear.
+6. **Report progress in Linear as a summary; acceptance stays with the requester.** Example: when the
+   last sub-issue closes, comment `Engineering complete: <epic URL>` on the Linear requirement and
+   leave its status alone.
+7. **An explicit destination from the user wins.** Example: "file this in Linear" files it in Linear.
+
+## Common wrong answers
+
+- "The request came from Linear, so the tickets go in Linear." The work type decides, rule 1.
+- "No tracker is configured, so use the one the conversation used." Resolve the repo, rule 2.
+- "Mirror the epic into Linear so stakeholders see it." Post a summary with a link, rule 5.
+- "All sub-issues closed, so the Linear requirement is done." Engineering complete is not accepted, rule 6.

package/skills/engineering/contributing/references/tracker-conventions.md

@@ -0,0 +1,18 @@
+## Issue tracking
+
+Engineering work for this repo is tracked in GitHub issues on `{{githubRepo}}`. Product work is tracked in Linear{{linearProjects}}.
+
+| Work item | Tracker |
+|---|---|
+| Product goals, business requirements, priorities, milestones | Linear |
+| Consulting engagements, reports, research deliverables | Linear |
+| Engineering specs and implementation epics | GitHub |
+| Implementation tickets, technical investigations, refactors, engineering bugs | GitHub |
+| Delivery progress for stakeholders | A summary in Linear that links to GitHub |
+
+1. **Classify the work before you create an issue; the tracker follows the work, not where the request came from.** Example: a spec written from a Linear requirement is a GitHub issue on `{{githubRepo}}`.
+2. **A Linear issue is a source reference, never a parent for implementation tickets.** Example: put `Source: https://linear.app/<team>/issue/DEV-123` in the GitHub epic body and make the tickets GitHub sub-issues of that epic; do not create DEV-124 under DEV-123.
+3. **Search GitHub before you create an issue.** Example: `gh issue list --repo {{githubRepo}} --state all --search "<keywords>"`; reuse or comment on a match instead of filing a duplicate.
+4. **Link back to Linear once per epic, not once per ticket.** Example: add the GitHub epic URL to the Linear requirement as a link; do not copy the GitHub tickets into Linear.
+5. **Report engineering progress in Linear as a summary; acceptance stays with the requester.** Example: when the last sub-issue closes, comment "Engineering complete: <epic URL>" on the Linear requirement and leave its status for the requester to move.
+6. **An explicit destination from the user wins.** Example: "file this in Linear" files it in Linear.

package/skills/engineering/contributing/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/engineering/contributing/scripts/persist-conventions-core.mjs

@@ -0,0 +1,118 @@
+// persist-conventions-core — write one skill's section into a repo's
+// CONTRIBUTING.md, point AGENTS.md at the file, and make CLAUDE.md a symlink to
+// AGENTS.md (Claude Code reads CLAUDE.md, not AGENTS.md). Import-only: each skill's
+// `persist-conventions.mjs` is the always-running CLI wrapper that names its
+// section, so no main-module guard here.
+//
+// Byte-identical copies live in test-quality (Testing conventions), github-flow
+// (CI conventions, Delivery), data-catalog (Data catalog conventions) and
+// contributing (Issue tracking);
+// skills/conventions-sections.test.mjs keeps them identical and proves the sections
+// coexist in one file.
+//
+// A section sits between `conventions:<id>` markers, so a re-run replaces only
+// that block and keeps everything else, including other skills' sections.
+// Nothing is written without --write: the user triggers the write, not an agent.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const CONTRIBUTING_FILE = 'CONTRIBUTING.md'
+const MENTIONS_CONTRIBUTING = /(?:^|[^\w-])CONTRIBUTING\.md/
+
+export const AGENTS_SECTION = [
+  '## Contributing',
+  '',
+  `Follow [${CONTRIBUTING_FILE}](${CONTRIBUTING_FILE}) when writing, reviewing, or delivering code, or creating issues: tests, CI, data definitions, issue tracking, and what to do after each commit.`,
+  '',
+].join('\n')
+
+export function markers(id) {
+  return [`<!-- conventions:${id}:start -->`, `<!-- conventions:${id}:end -->`]
+}
+
+export function sectionBlock({ id, owner, body }) {
+  const [start, end] = markers(id)
+  const note = `<!-- Written by the ${owner} skill: re-run its persist-conventions.mjs --write to update; edit outside these markers. -->`
+  return `${start}\n${note}\n\n${body.trim()}\n${end}\n`
+}
+
+// Pure: the new CONTRIBUTING.md text given the current one (or null).
+export function renderConventions(current, id, block) {
+  if (current == null) return `# Contributing\n\n${block}`
+  const [start, end] = markers(id)
+  const from = current.indexOf(start)
+  const to = current.indexOf(end)
+  if (from !== -1 && to > from) {
+    const after = current.slice(to + end.length).replace(/^\r?\n/, '')
+    return current.slice(0, from) + block + after
+  }
+  return `${current.replace(/\s*$/, '')}\n\n${block}`
+}
+
+// Pure: the new AGENTS.md text given the current one (or null).
+export function renderAgents(current) {
+  if (current == null) return `# AGENTS.md\n\n${AGENTS_SECTION}`
+  if (MENTIONS_CONTRIBUTING.test(current)) return current
+  return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
+}
+
+// A missing CLAUDE.md becomes a symlink to AGENTS.md.
+export const LINK_TO_AGENTS = Symbol('link CLAUDE.md to AGENTS.md')
+
+// Pure: the new CLAUDE.md text given the current one (or null). A missing file
+// becomes LINK_TO_AGENTS; a regular file keeps its content and gains the pointer
+// unless it already names AGENTS.md or CONTRIBUTING.md.
+export function renderClaude(current) {
+  if (current == null) return LINK_TO_AGENTS
+  if (/(?:^|[^\w-])(?:AGENTS|CONTRIBUTING)\.md/.test(current)) return current
+  return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
+}
+
+export function persist(repoRoot, section, { write = false } = {}) {
+  const block = sectionBlock(section)
+  const plan = [
+    [CONTRIBUTING_FILE, (text) => renderConventions(text, section.id, block)],
+    ['AGENTS.md', renderAgents],
+    ['CLAUDE.md', renderClaude],
+  ]
+  return plan.map(([name, render]) => {
+    const file = path.join(repoRoot, name)
+    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) return { file: name, action: 'unchanged' }
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
+    const next = render(current)
+    const action = current == null ? 'create' : next === current ? 'unchanged' : 'update'
+    if (next === LINK_TO_AGENTS) {
+      if (write) fs.symlinkSync('AGENTS.md', file)
+      return { file: name, action: 'link' }
+    }
+    if (write && action !== 'unchanged') fs.writeFileSync(file, next)
+    return { file: name, action }
+  })
+}
+
+// `section` = { id, owner, title, body }. Exit 0 on success, 2 on a usage error.
+export function runCli(argv, section, { cwd = process.cwd(), log = console.log } = {}) {
+  let repoRoot = cwd
+  let write = false
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--write') write = true
+    else if (argv[i] === '--repo-root' && argv[i + 1]) repoRoot = path.resolve(cwd, argv[++i])
+    else {
+      log(`persist-conventions: unknown argument ${argv[i]}`)
+      return 2
+    }
+  }
+  if (!fs.statSync(repoRoot, { throwIfNoEntry: false })?.isDirectory()) {
+    log(`persist-conventions: not a directory: ${repoRoot}`)
+    return 2
+  }
+  const results = persist(repoRoot, section, { write })
+  const done = { create: 'created', link: 'linked to AGENTS.md', update: 'updated', unchanged: 'unchanged' }
+  for (const r of results) log(`  ${r.file}: ${write || r.action === 'unchanged' ? done[r.action] : `would ${r.action}`}`)
+  const changed = results.filter((r) => r.action !== 'unchanged').length
+  log(write
+    ? `persist-conventions: ${section.title}: ${changed} file(s) written, ${results.length - changed} unchanged`
+    : `persist-conventions: ${section.title}: preview only, ${changed} file(s) would change; re-run with --write to write`)
+  return 0
+}

package/skills/engineering/contributing/scripts/persist-conventions.mjs

@@ -0,0 +1,84 @@
+// persist-conventions — the tracker routing rules as the `## Issue tracking`
+// section of a repo's CONTRIBUTING.md (../SKILL.md, First use in a repo).
+// Previews unless --write; --if-missing leaves an existing section alone.
+//
+//   node persist-conventions.mjs [--repo-root <dir>] [--github-repo <owner/name>]
+//     [--linear-project <name>]... [--if-missing] [--write]
+//
+// The GitHub repo defaults to the `origin` remote of --repo-root.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { CONTRIBUTING_FILE, LINK_TO_AGENTS, markers, renderAgents, renderClaude, runCli } from './persist-conventions-core.mjs'
+
+const ID = 'tracker'
+const TEMPLATE = fs.readFileSync(fileURLToPath(new URL('../references/tracker-conventions.md', import.meta.url)), 'utf8')
+
+function githubRepoFromRemote(url) {
+  const m = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(url.trim())
+  return m ? m[1] : null
+}
+
+function renderBody(githubRepo, linearProjects) {
+  const linear = linearProjects.length
+    ? ` (projects: ${linearProjects.join(', ')})`
+    : ''
+  return TEMPLATE.replaceAll('{{githubRepo}}', githubRepo).replaceAll('{{linearProjects}}', linear)
+}
+
+// The section stays as it is; only a missing AGENTS.md index or CLAUDE.md link is added.
+function indexOnly(repoRoot, write, log) {
+  let changed = 0
+  for (const [name, render] of [['AGENTS.md', renderAgents], ['CLAUDE.md', renderClaude]]) {
+    const file = path.join(repoRoot, name)
+    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) continue
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
+    const next = render(current)
+    if (next === current) continue
+    changed++
+    log(`  ${name}: ${write ? 'written' : 'would change'}`)
+    if (!write) continue
+    if (next === LINK_TO_AGENTS) fs.symlinkSync('AGENTS.md', file)
+    else fs.writeFileSync(file, next)
+  }
+  return changed ? `${changed} index file(s) ${write ? 'written' : 'would change'}` : 'nothing written'
+}
+
+function main(argv, { log = console.log } = {}) {
+  const rest = []
+  const linearProjects = []
+  let githubRepo = null
+  let ifMissing = false
+  let repoRoot = process.cwd()
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--linear-project' && argv[i + 1]) linearProjects.push(argv[++i])
+    else if (arg === '--github-repo' && argv[i + 1]) githubRepo = argv[++i]
+    else if (arg === '--if-missing') ifMissing = true
+    else {
+      if (arg === '--repo-root' && argv[i + 1]) repoRoot = path.resolve(argv[i + 1])
+      rest.push(arg)
+    }
+  }
+  if (!githubRepo) {
+    const remote = spawnSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+    githubRepo = remote.status === 0 ? githubRepoFromRemote(remote.stdout) : null
+  }
+  if (!githubRepo) {
+    log('persist-conventions: no GitHub origin remote; pass --github-repo <owner/name>')
+    return 2
+  }
+  if (ifMissing) {
+    const file = path.join(repoRoot, CONTRIBUTING_FILE)
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+    if (current.includes(markers(ID)[0])) {
+      log(`persist-conventions: Issue tracking: section already present; ${indexOnly(repoRoot, argv.includes('--write'), log)}`)
+      return 0
+    }
+  }
+  const section = { id: ID, owner: 'contributing', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
+  return runCli(rest, section, { log })
+}
+
+process.exitCode = main(process.argv.slice(2))