@1aboveio/core-skills 0.1.10 → 0.1.11
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/README.md +2 -1
- package/package.json +3 -3
- package/skills/distill-writing/SKILL.md +3 -3
- package/skills/distill-writing/references/extraction.md +1 -1
- package/skills/doc-to-md/SKILL.md +1 -1
- package/skills/editorial-review/SKILL.md +82 -12
- package/skills/editorial-review/references/checklist.md +26 -1
- package/skills/house-style/SKILL.md +8 -3
- package/skills/house-style/references/analytical-reporting.md +123 -0
- package/skills/house-style/references/analytical-writing-patterns.md +79 -0
- package/skills/house-style/references/analytical-writing-research.md +129 -0
- package/skills/{write-doc → house-style}/references/bilingual.md +7 -5
- package/skills/house-style/references/definitions-and-metrics.md +86 -0
- package/skills/house-style/references/document-workflow.md +193 -0
- package/skills/house-style/references/initialization.md +66 -0
- package/skills/house-style/references/persistence.md +9 -4
- package/skills/house-style/references/rules.md +11 -4
- package/skills/house-style/scripts/init-guidance.mjs +213 -0
- package/skills/house-style/templates/analytical-report.md +54 -0
- package/skills/house-style/templates/gap-analysis.md +1 -1
- package/skills/plain-language/SKILL.md +2 -2
- package/skills/polish-cn/SKILL.md +9 -2
- package/skills/reg-parser/SKILL.md +3 -3
- package/skills/terminology/SKILL.md +8 -4
- package/skills/write-doc/SKILL.md +40 -151
- package/skills/write-report/LICENSE +3 -0
- package/skills/write-report/SKILL.md +129 -0
- package/skills/{write-doc → write-report}/references/compliance-reports.md +4 -4
- package/skills/write-report/release-check.mjs +95 -0
- /package/skills/{write-doc → write-report}/references/reports/audit-report-template.md +0 -0
- /package/skills/{write-doc → write-report}/references/reports/external-assessment-template.md +0 -0
- /package/skills/{write-doc → write-report}/references/reports/management-report-template.md +0 -0
- /package/skills/{write-doc → write-report}/references/reports/vars-report-template.md +0 -0
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: write-report
|
|
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.45.0
|
|
5
|
+
---
|
|
6
|
+
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
7
|
+
# Write an analytical report
|
|
8
|
+
|
|
9
|
+
**Every analytical section must make a supported point. Its evidence should establish that
|
|
10
|
+
point, and its limitations should explain what would change the reader's interpretation or action.**
|
|
11
|
+
|
|
12
|
+
Explain what was examined, what was found, how strongly the sources support it, and what the
|
|
13
|
+
reader should decide or do. Recommendations may follow findings; they do not turn a report
|
|
14
|
+
into a proposal or authorize changing the underlying analysis.
|
|
15
|
+
|
|
16
|
+
An explicit user `/write-report` invocation first follows
|
|
17
|
+
[local initialization](../house-style/references/initialization.md) to persist `WRITING.md`,
|
|
18
|
+
`TERMINOLOGY.md` and their loading pointers. Automatic selection or a domain call does not
|
|
19
|
+
initialize guidance. This skill coordinates drafting, `editorial-review`, fixes, optional
|
|
20
|
+
`polish-cn`, regeneration and checks. The caller supplies domain requirements, not separate
|
|
21
|
+
commands for each writing stage. Standard mode is the default; explicit fast mode uses one
|
|
22
|
+
local review pass while preserving factual, analytical and domain requirements.
|
|
23
|
+
|
|
24
|
+
Before drafting or substantive editing, read the
|
|
25
|
+
[analytical reporting rules](../house-style/references/analytical-reporting.md), including their
|
|
26
|
+
required [writing patterns](../house-style/references/analytical-writing-patterns.md) and
|
|
27
|
+
[definitions and metrics](../house-style/references/definitions-and-metrics.md). These apply
|
|
28
|
+
even when another skill calls only this report stage. Load them for delegated writers and
|
|
29
|
+
reviewers too; a skill name or installed dependency does not transfer instructions.
|
|
30
|
+
|
|
31
|
+
Read and follow the [shared drafting and editing workflow](../house-style/references/document-workflow.md)
|
|
32
|
+
in full for source discipline, gaps, terminology, review, narrow edits and delivery. Follow
|
|
33
|
+
[house-style rules](../house-style/references/rules.md) for lookup and precedence. Start guidance
|
|
34
|
+
lookup beside the primary input file; with pasted input, start beside the output, else in the
|
|
35
|
+
working directory. Do not merge client guides or edit WRITING.md just because you read it.
|
|
36
|
+
Use [defaults](../house-style/references/defaults.md) and the applicable
|
|
37
|
+
[English](../house-style/references/style-en.md) or [Chinese](../house-style/references/style-zh.md)
|
|
38
|
+
guide where local guidance is silent. For Chinese or bilingual output, follow
|
|
39
|
+
[bilingual mode](../house-style/references/bilingual.md).
|
|
40
|
+
|
|
41
|
+
## Route and select
|
|
42
|
+
|
|
43
|
+
- Analytical reports of any subject stay here. Defining a requirement, policy, procedure,
|
|
44
|
+
or proposal belongs to `write-doc`. Reporting current-state gaps against an established
|
|
45
|
+
baseline stays here; defining new requirements belongs to `write-doc`.
|
|
46
|
+
A PRD for a reporting feature is not an analytical report. A short answer requested only
|
|
47
|
+
in chat does not require a saved report.
|
|
48
|
+
- Domain skills own the underlying work: payment metrics, fraud rules, contract review,
|
|
49
|
+
research methods and compliance assessment. If analysis is missing, use the appropriate
|
|
50
|
+
skill before writing its conclusions. Do not present a writing pass as a fresh audit,
|
|
51
|
+
rerun a domain pipeline unnecessarily, or fabricate results to fill a report.
|
|
52
|
+
- A domain skill may call this skill for its report stage. Keep its named template,
|
|
53
|
+
calculation definitions, validation requirements, charts, output format and artifacts.
|
|
54
|
+
Before drafting, note which outputs and checks that workflow requires, which are conditional,
|
|
55
|
+
and which are preferences, including any required Chinese polish. This skill completes the
|
|
56
|
+
writing stages and returns their checked version and open items. The domain workflow retains
|
|
57
|
+
remaining domain validation and delivery; it reuses completed writing passes rather than
|
|
58
|
+
repeating them. Its output requirements take precedence over this skill's Markdown default.
|
|
59
|
+
- For audit, external assessment, management assessment or VARS reports, read
|
|
60
|
+
[compliance reports](references/compliance-reports.md) before drafting or editing.
|
|
61
|
+
Board-facing analytical reports do not automatically need compliance checks; use the
|
|
62
|
+
assessment branch only when reporting a compliance assessment.
|
|
63
|
+
- Learning style or saving a future-report preference belongs to `distill-writing`.
|
|
64
|
+
For an explicit save during writing, follow its
|
|
65
|
+
[save procedure](../house-style/references/persistence.md), then resume. A one-off
|
|
66
|
+
correction stays local to this report.
|
|
67
|
+
|
|
68
|
+
Choose the user's or producing skill's explicit template first, then a matching project
|
|
69
|
+
template, then the relevant bundled layout (including
|
|
70
|
+
[gap-analysis](../house-style/templates/gap-analysis.md) for current state against a baseline).
|
|
71
|
+
Without one, use
|
|
72
|
+
[analytical-report](../house-style/templates/analytical-report.md). Mandated report structures
|
|
73
|
+
and wording remain protected; a style preference cannot override them.
|
|
74
|
+
|
|
75
|
+
## Establish the analytical basis
|
|
76
|
+
|
|
77
|
+
Before outlining a new report, record the reader's question, scope, source files and versions,
|
|
78
|
+
period, population, units, methods and limitations. Read the relevant source material, not
|
|
79
|
+
just a summary when the conclusion needs underlying detail. Ask once only for missing inputs
|
|
80
|
+
that block the reader's decision; otherwise narrow the claim and disclose the limitation.
|
|
81
|
+
|
|
82
|
+
- Trace material claims to source locations. Separate observed facts, calculations,
|
|
83
|
+
interpretations, assumptions and proposed actions. A hypothesis is not an established cause.
|
|
84
|
+
- Reconcile totals and derived metrics. State the numerator, denominator, exclusions, time
|
|
85
|
+
basis and units for rates. Do not treat missing observations as zero or extrapolate a
|
|
86
|
+
selected extract to a whole population without support.
|
|
87
|
+
- Compare like with like. Identify changes in scope, period, sample, currency or method.
|
|
88
|
+
Do not claim improvement, deterioration or significance from incomparable or absent baselines.
|
|
89
|
+
- Preserve source findings, IDs, ratings and uncertainty. Describe disagreements between
|
|
90
|
+
sources rather than silently choosing the more convenient number or conclusion.
|
|
91
|
+
- Use charts and tables when they help answer the question. Their populations, units, labels
|
|
92
|
+
and source values must agree with the prose. Keep supplied visual artifacts and links usable;
|
|
93
|
+
do not invent measurements or decorative data.
|
|
94
|
+
- Recommend actions proportionate to the findings. Costs, targets, owners, dates and expected
|
|
95
|
+
benefits need sources or explicit proposal/gap labels. State what the evidence cannot establish.
|
|
96
|
+
|
|
97
|
+
## Draft, review and deliver
|
|
98
|
+
|
|
99
|
+
Use the argument outline, definition checks and writing patterns from the required shared rules;
|
|
100
|
+
follow the shared workflow with the selected template. Keep this sequence visible in working
|
|
101
|
+
notes or the task checklist so loading instructions is not confused with executing a review:
|
|
102
|
+
|
|
103
|
+
1. Draft and save the report and its required charts/tables from the established results.
|
|
104
|
+
2. Reopen that saved version and run `editorial-review` with the selected template, sources,
|
|
105
|
+
review mode and applicable domain checks. Save its brief review result to an existing working
|
|
106
|
+
file or a scratch file: identify the version, reader answers and concrete source checks,
|
|
107
|
+
even with no findings. A reread followed by a clean-review claim does not complete this stage.
|
|
108
|
+
Record findings before fixing; apply fixes and recheck changed claims against the sources.
|
|
109
|
+
3. For Chinese text, execute `polish-cn` only when selected by the user or required by local or
|
|
110
|
+
domain policy, after content and any bilingual equivalence are final. Installation alone does
|
|
111
|
+
not select polish. Fast mode skips only optional polish, not an explicit or required pass.
|
|
112
|
+
4. Regenerate when applicable and inspect the final reader-facing outputs. Check required
|
|
113
|
+
artifacts, source links and domain checks, not just the prose. A table or a description of a
|
|
114
|
+
chart does not satisfy a chart requirement. Record missing work as incomplete.
|
|
115
|
+
5. Return to the producing workflow when there is one; otherwise deliver as below. Keep review
|
|
116
|
+
notes outside the business report. Reuse the saved working review record rather than
|
|
117
|
+
creating another review artifact.
|
|
118
|
+
|
|
119
|
+
For a narrow edit, use the shared narrow-edit branch. Verify affected claims and linked totals;
|
|
120
|
+
do not demand the entire dataset for an unrelated spelling correction. Reassessment, new
|
|
121
|
+
substantive claims and finalization require the supporting sources and applicable full checks.
|
|
122
|
+
|
|
123
|
+
Save to the requested path or format, else the project's output location, else
|
|
124
|
+
`./analytical-report-<short-topic>.md`; compliance-specific filenames follow their reference.
|
|
125
|
+
For a requested DOCX or PDF, render and inspect that export as well. Check citations and asset
|
|
126
|
+
links from the final location. Do not copy confidential sources into a delivery bundle without
|
|
127
|
+
authorization. Report the path, guidance and template used, checks performed, unresolved material
|
|
128
|
+
gaps, proposed decisions and limits on the conclusions. Do not claim a missing analysis, review,
|
|
129
|
+
export or external approval was completed.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Compliance reports
|
|
2
2
|
|
|
3
|
-
Use this reference within the `write-
|
|
3
|
+
Use this reference within the `write-report` workflow when audit findings become a report.
|
|
4
4
|
It replaces the retired `report-writing` skill. For a narrow edit to an existing report, use
|
|
5
5
|
[the edit branch](#edit-an-existing-report) before the full-report steps below.
|
|
6
6
|
Do not repeat the audit or silently change
|
|
@@ -29,7 +29,7 @@ that is not a report of an assessment.
|
|
|
29
29
|
## Edit an existing report
|
|
30
30
|
|
|
31
31
|
A copy-edit that changes no finding, rating, scope, count, recommendation or mandated text
|
|
32
|
-
follows `write-
|
|
32
|
+
follows `write-report`'s narrow-edit workflow. Read the existing report and applicable guidance;
|
|
33
33
|
verify only the passages and facts affected by the change. Do not require the complete tracker
|
|
34
34
|
for an unrelated spelling or formatting correction, re-audit the report, or call the edit a
|
|
35
35
|
new assessment or finalization. Preserve protected text and all unaffected content.
|
|
@@ -46,7 +46,7 @@ category, status (Pass / Fail / Partial / N/A), severity (Critical / Major / Min
|
|
|
46
46
|
Observation), observations, evidence and recommendations. Normalize other input shapes
|
|
47
47
|
without inventing missing values. Flag missing status or severity; never turn an unknown
|
|
48
48
|
into Pass or a lower severity. Mark missing evidence as **Evidence Pending**, keeping
|
|
49
|
-
the finding visible. Missing facts follow `write-
|
|
49
|
+
the finding visible. Missing facts follow `write-report`'s gap rules.
|
|
50
50
|
|
|
51
51
|
Preserve original IDs. Assign `F-001`, `F-002`, and so on only when IDs are absent.
|
|
52
52
|
Link findings to remediation and evidence by ID. Keep source ratings, scales, findings
|
|
@@ -85,7 +85,7 @@ without checking it.
|
|
|
85
85
|
|
|
86
86
|
## Draft and review
|
|
87
87
|
|
|
88
|
-
Use `write-
|
|
88
|
+
Use `write-report`'s outline, draft, editorial review, fix and delivery steps. Apply the
|
|
89
89
|
nearest WRITING.md from the findings file's directory, or for pasted input the output
|
|
90
90
|
directory, else the working directory, under the shared lookup rules. Never edit it.
|
|
91
91
|
For non-VARS reports, follow the selected template's structure. House style must not change
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { spawnSync } from 'node:child_process';
|
|
3
|
+
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { homedir } from 'node:os';
|
|
5
|
+
import { dirname, join, resolve } from 'node:path';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
|
|
8
|
+
const DAY_MS = 24 * 60 * 60 * 1000;
|
|
9
|
+
const WEEK_MS = 7 * DAY_MS;
|
|
10
|
+
const here = dirname(fileURLToPath(import.meta.url));
|
|
11
|
+
|
|
12
|
+
function readJson(path, fallback = {}) {
|
|
13
|
+
try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function frontmatterValue(text, key) {
|
|
17
|
+
const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
|
|
18
|
+
const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
|
|
19
|
+
return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function repositoryOf(source) {
|
|
23
|
+
const value = String(source ?? '').trim();
|
|
24
|
+
const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
|
|
25
|
+
return match?.[1] ?? null;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function stableVersion(value) {
|
|
29
|
+
const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
|
|
30
|
+
return match ? match.slice(1).map(Number) : null;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function newer(left, right) {
|
|
34
|
+
for (let index = 0; index < 3; index += 1) {
|
|
35
|
+
if (left[index] !== right[index]) return left[index] > right[index];
|
|
36
|
+
}
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function writeCache(path, value) {
|
|
41
|
+
try {
|
|
42
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
43
|
+
writeFileSync(path, JSON.stringify(value));
|
|
44
|
+
} catch { /* A read-only cache must not block skill use. */ }
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function main(now = Date.now()) {
|
|
48
|
+
if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
|
|
49
|
+
const bundle = readJson(join(resolve(here, '../../..'), 'package.json'));
|
|
50
|
+
if (bundle.name === '@1aboveio/skills' && bundle.nativeCodex?.schemaVersion === 1) return;
|
|
51
|
+
const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
|
|
52
|
+
const name = frontmatterValue(skill, 'name');
|
|
53
|
+
const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
|
|
54
|
+
if (!name || !localVersion) return;
|
|
55
|
+
|
|
56
|
+
const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
|
|
57
|
+
const entry = lock.skills?.[name];
|
|
58
|
+
const repository = repositoryOf(entry?.sourceUrl || entry?.source);
|
|
59
|
+
if (!repository) return;
|
|
60
|
+
|
|
61
|
+
const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
|
|
62
|
+
const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
|
|
63
|
+
const all = readJson(cachePath);
|
|
64
|
+
const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
|
|
65
|
+
|
|
66
|
+
if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
|
|
67
|
+
const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
|
|
68
|
+
encoding: 'utf8',
|
|
69
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
70
|
+
timeout: 1500,
|
|
71
|
+
});
|
|
72
|
+
cache.lastCheck = now;
|
|
73
|
+
if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
|
|
74
|
+
else delete cache.latestTag;
|
|
75
|
+
all[repository] = cache;
|
|
76
|
+
writeCache(cachePath, all);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const latestVersion = stableVersion(cache.latestTag);
|
|
80
|
+
if (!latestVersion || !newer(latestVersion, localVersion)) return;
|
|
81
|
+
if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
|
|
82
|
+
|
|
83
|
+
cache.notifiedTag = cache.latestTag;
|
|
84
|
+
cache.notifiedAt = now;
|
|
85
|
+
all[repository] = cache;
|
|
86
|
+
writeCache(cachePath, all);
|
|
87
|
+
const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
|
|
88
|
+
process.stdout.write(
|
|
89
|
+
`UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
|
|
90
|
+
+ `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
|
|
91
|
+
+ 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
|
|
File without changes
|
/package/skills/{write-doc → write-report}/references/reports/external-assessment-template.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|