@1aboveio/content-skills 0.0.0-stage → 0.1.0

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.
Files changed (53) hide show
  1. package/README.md +24 -2
  2. package/package.json +33 -4
  3. package/skills/article-review/LICENSE +3 -0
  4. package/skills/article-review/SKILL.md +66 -0
  5. package/skills/article-review/references/report-format.md +68 -0
  6. package/skills/article-review/references/template-guide.md +79 -0
  7. package/skills/article-review/references/template-wechat-payments.md +125 -0
  8. package/skills/article-review/release-check.mjs +93 -0
  9. package/skills/article-to-image/LICENSE +3 -0
  10. package/skills/article-to-image/SKILL.md +91 -0
  11. package/skills/article-to-image/references/formats.md +53 -0
  12. package/skills/article-to-image/release-check.mjs +93 -0
  13. package/skills/flowchart-svg/LICENSE +3 -0
  14. package/skills/flowchart-svg/SKILL.md +43 -0
  15. package/skills/flowchart-svg/release-check.mjs +93 -0
  16. package/skills/flowchart-svg/scripts/export_png.sh +8 -0
  17. package/skills/image-gen/LICENSE +3 -0
  18. package/skills/image-gen/SKILL.md +192 -0
  19. package/skills/image-gen/release-check.mjs +93 -0
  20. package/skills/image-gen/scripts/credentials.mjs +217 -0
  21. package/skills/image-gen/scripts/credentials.test.mjs +212 -0
  22. package/skills/image-gen/scripts/generate.mjs +240 -0
  23. package/skills/image-gen/scripts/options.mjs +293 -0
  24. package/skills/image-gen/scripts/options.test.mjs +245 -0
  25. package/skills/mermaid/LICENSE +3 -0
  26. package/skills/mermaid/SKILL.md +635 -0
  27. package/skills/mermaid/release-check.mjs +93 -0
  28. package/skills/wechat-article-writer/LICENSE +3 -0
  29. package/skills/wechat-article-writer/SKILL.md +92 -0
  30. package/skills/wechat-article-writer/references/style-selector.md +133 -0
  31. package/skills/wechat-article-writer/references/writing-rules.md +152 -0
  32. package/skills/wechat-article-writer/release-check.mjs +93 -0
  33. package/skills/wechat-article-writer/templates/wechat-comparison.md +52 -0
  34. package/skills/wechat-article-writer/templates/wechat-howto.md +51 -0
  35. package/skills/wechat-article-writer/templates/wechat-insight.md +50 -0
  36. package/skills/wechat-article-writer/templates/wechat-pitfall.md +52 -0
  37. package/skills/wechat-publisher/LICENSE +3 -0
  38. package/skills/wechat-publisher/SKILL.md +171 -0
  39. package/skills/wechat-publisher/references/api.md +105 -0
  40. package/skills/wechat-publisher/references/layout-rules.md +57 -0
  41. package/skills/wechat-publisher/references/wechat-safe-template.html +86 -0
  42. package/skills/wechat-publisher/release-check.mjs +93 -0
  43. package/skills/wechat-publisher/scripts/md_to_wechat_html.py +194 -0
  44. package/skills/wechat-publisher/scripts/publish.py +239 -0
  45. package/skills/wechat-search/LICENSE +3 -0
  46. package/skills/wechat-search/SKILL.md +211 -0
  47. package/skills/wechat-search/release-check.mjs +93 -0
  48. package/skills/wechat-search/scripts/start-chrome.sh +83 -0
  49. package/skills/xai-search/LICENSE +3 -0
  50. package/skills/xai-search/SKILL.md +79 -0
  51. package/skills/xai-search/release-check.mjs +93 -0
  52. package/skills/xai-search/scripts/xai_search.sh +187 -0
  53. package/skills/xai-search/tests/smoke_test.sh +36 -0
@@ -0,0 +1,93 @@
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 } 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 skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
50
+ const name = frontmatterValue(skill, 'name');
51
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
52
+ if (!name || !localVersion) return;
53
+
54
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
55
+ const entry = lock.skills?.[name];
56
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
57
+ if (!repository) return;
58
+
59
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
60
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
61
+ const all = readJson(cachePath);
62
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
63
+
64
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
65
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
66
+ encoding: 'utf8',
67
+ stdio: ['ignore', 'pipe', 'ignore'],
68
+ timeout: 1500,
69
+ });
70
+ cache.lastCheck = now;
71
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
72
+ else delete cache.latestTag;
73
+ all[repository] = cache;
74
+ writeCache(cachePath, all);
75
+ }
76
+
77
+ const latestVersion = stableVersion(cache.latestTag);
78
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
79
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
80
+
81
+ cache.notifiedTag = cache.latestTag;
82
+ cache.notifiedAt = now;
83
+ all[repository] = cache;
84
+ writeCache(cachePath, all);
85
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
86
+ process.stdout.write(
87
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
88
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
89
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
90
+ );
91
+ }
92
+
93
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
@@ -0,0 +1,3 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 1AboveIO
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: flowchart-svg
3
+ description: Create polished flowcharts directly as SVG and export PNG copies. Use when asked to draw, design, render, or deliver process diagrams, architecture diagrams, consulting workflows, decision flows, swimlanes, or other flowcharts as image files, especially when final outputs must include .svg and .png versions.
4
+ release-version: 0.36.0
5
+ ---
6
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
+ # Flowchart SVG
8
+
9
+ Use this skill to produce clean, editable SVG flowcharts and matching PNG exports.
10
+
11
+ ## Workflow
12
+
13
+ 1. Identify the diagram purpose, audience, title, nodes, edges, and feedback loops.
14
+ 2. Choose a simple layout before writing SVG: left-to-right for pipelines, top-to-bottom for procedures.
15
+ 3. Draw directly in SVG with explicit coordinates; avoid Mermaid screenshots unless requested.
16
+ 4. Use semantic color groups: input, AI/automation, human judgment, reusable assets, outputs, feedback.
17
+ 5. Keep text short; split long labels into multiple text lines rather than relying on wrapping.
18
+ 6. Export PNG from the SVG with rsvg-convert or the bundled shell helper.
19
+ 7. Send the PNG to the user by default, because SVG is often unsupported in chat and document surfaces.
20
+ 8. Include the SVG as an editable source file when the channel supports attachments or when the user explicitly asks for it.
21
+ 9. Inspect both outputs before delivery.
22
+
23
+ ## Quality Bar
24
+
25
+ - Include a title and one-line subtitle when helpful.
26
+ - Use viewBox, markers for arrows, rounded rectangles, and consistent spacing.
27
+ - Use readable fonts with fallbacks, normally Arial, Noto Sans CJK SC, sans-serif.
28
+ - Avoid tiny text; body text should normally be at least 13px in a 1200px-wide diagram.
29
+ - Keep arrows from crossing boxes where possible.
30
+
31
+ ## Export
32
+
33
+ Use the helper script:
34
+
35
+ ```bash
36
+ scripts/export_png.sh input.svg output.png
37
+ ```
38
+
39
+ If the helper is unavailable, run:
40
+
41
+ ```bash
42
+ rsvg-convert -w 2400 -f png input.svg -o output.png
43
+ ```
@@ -0,0 +1,93 @@
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 } 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 skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
50
+ const name = frontmatterValue(skill, 'name');
51
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
52
+ if (!name || !localVersion) return;
53
+
54
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
55
+ const entry = lock.skills?.[name];
56
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
57
+ if (!repository) return;
58
+
59
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
60
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
61
+ const all = readJson(cachePath);
62
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
63
+
64
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
65
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
66
+ encoding: 'utf8',
67
+ stdio: ['ignore', 'pipe', 'ignore'],
68
+ timeout: 1500,
69
+ });
70
+ cache.lastCheck = now;
71
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
72
+ else delete cache.latestTag;
73
+ all[repository] = cache;
74
+ writeCache(cachePath, all);
75
+ }
76
+
77
+ const latestVersion = stableVersion(cache.latestTag);
78
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
79
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
80
+
81
+ cache.notifiedTag = cache.latestTag;
82
+ cache.notifiedAt = now;
83
+ all[repository] = cache;
84
+ writeCache(cachePath, all);
85
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
86
+ process.stdout.write(
87
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
88
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
89
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
90
+ );
91
+ }
92
+
93
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+ if [ "$#" -ne 2 ]; then
4
+ echo "Usage: export_png.sh input.svg output.png" >&2
5
+ exit 2
6
+ fi
7
+ rsvg-convert -w 2400 -f png "$1" -o "$2"
8
+ echo "$2"
@@ -0,0 +1,3 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 1AboveIO
@@ -0,0 +1,192 @@
1
+ ---
2
+ name: image-gen
3
+ description: Generate an image from a text prompt with OpenAI gpt-image-2 or Google Nano Banana (Gemini), saved to an image file. Use whenever the user asks to generate, create, make, draw, paint, render, or design an image, picture, illustration, photo, artwork, logo, icon, avatar, banner, hero image, thumbnail, poster, wallpaper, sticker, or concept art — including phrasings like "an image of X", "a picture of X", "show me what X would look like", or a request for a visual for a slide, blog post, README, or social post. Also triggers on Chinese phrasings such as 生成图片, 画一张图, 做一张海报, 设计一个 logo. NOT for charts or data visualizations (dataviz), flowcharts or architecture diagrams (flowchart-svg), or editing an existing image file.
4
+ release-version: 0.36.0
5
+ ---
6
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
+ # Image Generation
8
+
9
+ Text prompt in, image file on disk out. Two providers: **OpenAI gpt-image-2** (default)
10
+ and **Google Nano Banana** (Gemini).
11
+
12
+ ## Run it
13
+
14
+ ```bash
15
+ node <SKILL_ROOT>/scripts/generate.mjs "your image prompt here"
16
+ ```
17
+
18
+ The script prints the endpoint it used, then the saved path. Defaults: `openai`
19
+ provider, `gpt-image-2`, `1024x1024`, output `./generated-{timestamp}.png`.
20
+
21
+ ## Options
22
+
23
+ | Flag | Default | Description |
24
+ |------|---------|-------------|
25
+ | `--provider` | `openai` | `openai` or `gemini` |
26
+ | `--model` | provider-specific | Model name (see Models below) |
27
+ | `--size` | provider default | OpenAI: `1024x1024`, `1536x1024`, `1024x1536`, `auto`. Gemini: `WxH` or an aspect ratio |
28
+ | `--quality` | `auto` | `low`, `medium`, `high`, `auto` — **OpenAI only**, warned and ignored for Gemini |
29
+ | `--output` | `./generated-{timestamp}.{ext}` | Output file path; parent dirs are created |
30
+
31
+ Both `--flag value` and `--flag=value` work. An unknown flag is an error rather
32
+ than a silent no-op — a dropped `--qualtiy` produces an image at the wrong setting
33
+ with no hint of why, so the script names the typo and suggests the real flag.
34
+
35
+ ### Size on Gemini
36
+
37
+ Gemini takes an aspect **ratio**, not pixel dimensions, so `--size` accepts either
38
+ form and a `WxH` value is snapped to the closest ratio the API supports:
39
+
40
+ | You pass | Gemini receives |
41
+ |----------|-----------------|
42
+ | `1536x1024` | `3:2` |
43
+ | `1920x1080` | `16:9` |
44
+ | `16:9` | `16:9` (passed straight through) |
45
+ | omitted or `auto` | nothing — the model's own default |
46
+
47
+ Supported ratios are `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`,
48
+ `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`. A snap is printed when it happens, so
49
+ the ratio you got is never a silent substitution.
50
+
51
+ ### Output format
52
+
53
+ The saved extension follows the bytes the provider actually returned, so a JPEG
54
+ never lands in a `.png`. An explicit `--output` is always honored — overriding
55
+ your chosen path would be worse — but a mismatch prints a warning, since some
56
+ viewers and upload validators reject a mislabeled file.
57
+
58
+ The run prints the dimensions actually returned, and warns when they differ from
59
+ what was asked for. Providers and proxies do not reliably honor `size`: a gateway
60
+ under test returned 1536x1024 exactly as requested, then answered a 1024x1536
61
+ request with 1402x1122. Trust the printed dimensions over the flag.
62
+
63
+ Requests time out after 180s with a clear message rather than hanging forever on a
64
+ stalled gateway.
65
+
66
+ ## Credentials
67
+
68
+ **OpenAI** — resolved in this order, first match wins:
69
+
70
+ | Order | Source | Key | Base URL |
71
+ |-------|--------|-----|----------|
72
+ | 1 | Environment | `OPENAI_API_KEY` | `OPENAI_BASE_URL`, else `https://api.openai.com/v1` |
73
+ | 2 | pi harness config | `providers.openai.apiKey` | `providers.openai.baseUrl`, else the OpenAI default |
74
+ | 3 | — | error, naming both sources | — |
75
+
76
+ The pi config lives at `~/.pi/agent/models.json` (override the directory with
77
+ `PI_CODING_AGENT_DIR`). It is read only when `OPENAI_API_KEY` is unset.
78
+
79
+ ### pi values are templates, not literals
80
+
81
+ pi config values are resolved against the environment, so `apiKey` is very often
82
+ `"$OPENAI_API_KEY"` rather than the key itself. This script applies pi's own
83
+ grammar (`core/resolve-config-value.js`) before using a value:
84
+
85
+ | Value | Resolves to |
86
+ |-------|-------------|
87
+ | `sk-abc` | itself — a literal |
88
+ | `$VAR`, `${VAR}` | the environment variable; an empty variable counts as unset |
89
+ | `https://$HOST/v1` | expansion inside surrounding text |
90
+ | `$$` / `$!` | a literal `$` / `!` |
91
+ | `!some command` | **not executed** — reported as unsupported, set the env var instead |
92
+
93
+ If any referenced variable is unset, the value is unusable and the run stops with
94
+ a message naming the variable. It is never sent as a bearer token verbatim.
95
+
96
+ **A pi entry reading `$OPENAI_API_KEY` can never satisfy this fallback**, since
97
+ the fallback only runs when that variable is absent — the template then resolves
98
+ to nothing. To make the pi path usable, point it at a different variable
99
+ (`$GAPSEE_KEY`) or store the key literally. The error message says this outright
100
+ when it happens.
101
+
102
+ **The key and base URL always come from the same source.** When the key falls back
103
+ to pi, `OPENAI_BASE_URL` is deliberately ignored — pairing a pi key with an
104
+ unrelated gateway would send the key somewhere it does not authenticate. The run
105
+ banner prints which source won, so a surprising endpoint is visible immediately.
106
+
107
+ **Gemini** — `GEMINI_API_KEY` only; there is no pi fallback.
108
+
109
+ Custom gateways work for either style of source: trailing slashes are stripped and
110
+ `/images/generations` is appended.
111
+
112
+ ## Models
113
+
114
+ | Provider | Model | Best for |
115
+ |----------|-------|----------|
116
+ | `openai` | `gpt-image-2` (default) | General generation, prompt adherence |
117
+ | `gemini` | `gemini-3-pro-image-preview` (default) | Nano Banana Pro — high quality, text rendering, complex prompts |
118
+ | `gemini` | `gemini-3.1-flash-image-preview` | Nano Banana 2 — fast, good quality |
119
+ | `gemini` | `gemini-2.5-flash-image` | Nano Banana — fastest, efficient |
120
+
121
+ ## Examples
122
+
123
+ ```bash
124
+ # OpenAI (default)
125
+ node <SKILL_ROOT>/scripts/generate.mjs "A serene mountain landscape at sunset"
126
+
127
+ # OpenAI with options
128
+ node <SKILL_ROOT>/scripts/generate.mjs "Logo design for a tech startup" \
129
+ --size 1024x1024 --quality high --output logo.png
130
+
131
+ # Gemini Nano Banana Pro
132
+ node <SKILL_ROOT>/scripts/generate.mjs "A watercolor painting of Tokyo" --provider gemini
133
+
134
+ # Gemini Nano Banana 2 (faster)
135
+ node <SKILL_ROOT>/scripts/generate.mjs "Product photo, white background" \
136
+ --provider gemini --model gemini-3.1-flash-image-preview
137
+ ```
138
+
139
+ ## Workflow
140
+
141
+ 1. **Clarify** — if the request is vague, ask for specifics (style, subject, mood,
142
+ colors, composition) before spending a generation.
143
+ 2. **Enhance** — expand the user's words into a full prompt using the recipe below.
144
+ Say what you added, so they can steer it.
145
+ 3. **Generate** — run the script.
146
+ 4. **Show** — read the saved image back so the user sees it inline, and give the path.
147
+ 5. **Iterate** — offer variations: different style, composition, or palette.
148
+
149
+ ## Writing the prompt
150
+
151
+ Stack these five, in roughly this order — each one removes a decision the model
152
+ would otherwise make for you:
153
+
154
+ | Element | Examples |
155
+ |---------|----------|
156
+ | Subject | "a red fox curled asleep", "a ceramic coffee cup" |
157
+ | Style | "watercolor illustration", "photorealistic", "flat vector art", "1950s screen print" |
158
+ | Composition | "centered", "close-up", "wide angle", "bird's eye view", "rule of thirds" |
159
+ | Lighting | "golden hour", "studio lighting", "dramatic shadows", "soft diffused light" |
160
+ | Color | "warm tones", "monochromatic blue", "muted pastels", "high contrast" |
161
+
162
+ Add the destination when it constrains the frame — "for a blog header", "square
163
+ social avatar", "presentation slide background with room for text on the left".
164
+
165
+ Pick the size to match: `1536x1024` for banners and headers, `1024x1536` for
166
+ posters and phone wallpapers, `1024x1024` for avatars, icons, and social posts.
167
+
168
+ ## Troubleshooting
169
+
170
+ | Symptom | Cause and fix |
171
+ |---------|---------------|
172
+ | `no usable OpenAI credentials` | Neither source yielded a key. The message names the config path and any unresolved `$VAR` it found. |
173
+ | pi config has a key but is still rejected | Its value is a `$VAR` template whose variable is unset — commonly `$OPENAI_API_KEY` itself, which cannot work here (see above). |
174
+ | `401` while the config "looks right" | Check whether an older copy of this script sent the template verbatim; the endpoint line now prints the resolved source. |
175
+ | Requests hit an unexpected host | Check the `Endpoint:` line in the run banner — it names the winning source. An env key with a stale `OPENAI_BASE_URL` overrides the pi gateway. |
176
+ | `401`/`403` from a custom gateway | Key and gateway are mismatched. Set both env vars together, or unset `OPENAI_API_KEY` to use the pi pair. |
177
+ | `model not found` on a gateway | Not every proxy carries `gpt-image-2`; pass `--model`, or use `--provider gemini`. |
178
+ | `No image data in response` | The endpoint answered but returned no image — usually a proxy that does not implement `/images/generations`. |
179
+ | Content refusals | Rephrase away from real people, trademarks, and named living artists. |
180
+ | Image came back the wrong shape | The provider ignored `size`. The run warns when this happens; try a different model, or crop afterwards. |
181
+ | `429` / quota exceeded on Gemini | The key has no image quota — Gemini image models are not on the free tier. |
182
+
183
+ ## Tests
184
+
185
+ ```bash
186
+ node --test <SKILL_ROOT>/scripts/*.test.mjs
187
+ ```
188
+
189
+ `credentials.test.mjs` covers the resolution order above (env precedence, pi
190
+ template expansion, the same-source rule, malformed and missing configs).
191
+ `options.test.mjs` covers flag parsing, the Gemini ratio snapping, and output
192
+ naming. Neither touches the network.
@@ -0,0 +1,93 @@
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 } 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 skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
50
+ const name = frontmatterValue(skill, 'name');
51
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
52
+ if (!name || !localVersion) return;
53
+
54
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
55
+ const entry = lock.skills?.[name];
56
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
57
+ if (!repository) return;
58
+
59
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
60
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
61
+ const all = readJson(cachePath);
62
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
63
+
64
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
65
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
66
+ encoding: 'utf8',
67
+ stdio: ['ignore', 'pipe', 'ignore'],
68
+ timeout: 1500,
69
+ });
70
+ cache.lastCheck = now;
71
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
72
+ else delete cache.latestTag;
73
+ all[repository] = cache;
74
+ writeCache(cachePath, all);
75
+ }
76
+
77
+ const latestVersion = stableVersion(cache.latestTag);
78
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
79
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
80
+
81
+ cache.notifiedTag = cache.latestTag;
82
+ cache.notifiedAt = now;
83
+ all[repository] = cache;
84
+ writeCache(cachePath, all);
85
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
86
+ process.stdout.write(
87
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
88
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
89
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
90
+ );
91
+ }
92
+
93
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }