@1aboveio/content-skills 0.0.0-stage → 0.1.1
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 +24 -2
- package/package.json +34 -4
- package/skills/article-review/LICENSE +3 -0
- package/skills/article-review/SKILL.md +66 -0
- package/skills/article-review/references/report-format.md +68 -0
- package/skills/article-review/references/template-guide.md +79 -0
- package/skills/article-review/references/template-wechat-payments.md +125 -0
- package/skills/article-review/release-check.mjs +93 -0
- package/skills/article-to-image/LICENSE +3 -0
- package/skills/article-to-image/SKILL.md +91 -0
- package/skills/article-to-image/references/formats.md +53 -0
- package/skills/article-to-image/release-check.mjs +93 -0
- package/skills/flowchart-svg/LICENSE +3 -0
- package/skills/flowchart-svg/SKILL.md +43 -0
- package/skills/flowchart-svg/release-check.mjs +93 -0
- package/skills/flowchart-svg/scripts/export_png.sh +8 -0
- package/skills/image-gen/LICENSE +3 -0
- package/skills/image-gen/SKILL.md +192 -0
- package/skills/image-gen/release-check.mjs +93 -0
- package/skills/image-gen/scripts/credentials.mjs +217 -0
- package/skills/image-gen/scripts/credentials.test.mjs +212 -0
- package/skills/image-gen/scripts/generate.mjs +240 -0
- package/skills/image-gen/scripts/options.mjs +293 -0
- package/skills/image-gen/scripts/options.test.mjs +245 -0
- package/skills/mermaid/LICENSE +3 -0
- package/skills/mermaid/SKILL.md +635 -0
- package/skills/mermaid/release-check.mjs +93 -0
- package/skills/wechat-article-writer/LICENSE +3 -0
- package/skills/wechat-article-writer/SKILL.md +92 -0
- package/skills/wechat-article-writer/references/style-selector.md +133 -0
- package/skills/wechat-article-writer/references/writing-rules.md +152 -0
- package/skills/wechat-article-writer/release-check.mjs +93 -0
- package/skills/wechat-article-writer/templates/wechat-comparison.md +52 -0
- package/skills/wechat-article-writer/templates/wechat-howto.md +51 -0
- package/skills/wechat-article-writer/templates/wechat-insight.md +50 -0
- package/skills/wechat-article-writer/templates/wechat-pitfall.md +52 -0
- package/skills/wechat-publisher/LICENSE +3 -0
- package/skills/wechat-publisher/SKILL.md +171 -0
- package/skills/wechat-publisher/references/api.md +105 -0
- package/skills/wechat-publisher/references/layout-rules.md +57 -0
- package/skills/wechat-publisher/references/wechat-safe-template.html +86 -0
- package/skills/wechat-publisher/release-check.mjs +93 -0
- package/skills/wechat-publisher/scripts/md_to_wechat_html.py +194 -0
- package/skills/wechat-publisher/scripts/publish.py +239 -0
- package/skills/wechat-search/LICENSE +3 -0
- package/skills/wechat-search/SKILL.md +211 -0
- package/skills/wechat-search/release-check.mjs +93 -0
- package/skills/wechat-search/scripts/start-chrome.sh +83 -0
- package/skills/xai-search/LICENSE +3 -0
- package/skills/xai-search/SKILL.md +79 -0
- package/skills/xai-search/release-check.mjs +93 -0
- package/skills/xai-search/scripts/xai_search.sh +187 -0
- 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,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.38.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,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.38.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. */ }
|