gstack/skills/qa/references/legacy/skillify.md

Host-neutral runtime bindings

These assignments select stable paths only; they do not install anything or grant consent:

GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
GSTACK_ROOT="$GSTACK_HOME"
GSTACK_STATE_ROOT="$GSTACK_HOME"
GSTACK_BIN="$GSTACK_HOME/bin"
BUN_CMD="$GSTACK_BIN/bun"
B="$GSTACK_BIN/browse"
D="$GSTACK_BIN/gstack-design"
P="$GSTACK_BIN/make-pdf"

$qa --mode Report --module skillify — codify the last scrape into a permanent skill

The productivity multiplier. $qa --mode Report --module scrape discovered how to pull the data; $qa --mode Report --module skillify writes it as deterministic Playwright-via-browse-client code so the next $qa --mode Report --module scrape call on the same intent runs in ~200ms.

Without this command, $qa --mode Report --module scrape is a slow wrapper around $B. With it, every successful scrape is a one-time cost.

Iron contract — never write a half-broken skill to disk

Skills are user-trust artifacts. A broken skill in $B skill list makes agents reach for the wrong tool and erodes confidence. This skill writes to a temp dir, runs the auto-generated test there, and only renames into the final tier path on (a) test pass + (b) explicit user approval. On either failure, the temp dir is removed entirely. There is no "almost shipped" state.

---

Step 1 — Provenance guard (D1)

Walk back through the conversation, at most 10 agent turns, looking for the most recent $qa --mode Report --module scrape invocation that:

• Was bounded (you can identify the user's intent line and the trailing JSON the prototype produced)
• Produced a JSON result the user did not subsequently invalidate (e.g., did not say "that's wrong", did not ask you to retry)

If you cannot find one, refuse with exactly this message:

"No recent $qa --mode Report --module scrape result found in this conversation. Run $qa --mode Report --module scrape first, then say $qa --mode Report --module skillify."

Stop. Do not synthesize from chat fragments. Do not synthesize from a match-path $qa --mode Report --module scrape result (matched skills are already codified — there's nothing to skillify).

If you find a candidate but the user is currently three turns past it discussing something unrelated, ask once before proceeding:

"The last successful $qa --mode Report --module scrape was '' a few turns back. Skillify that one?"

A "yes" lets you continue. Anything else: refuse with the message above.

Step 2 — Propose name + triggers

From the prototype intent, extract:

• A short skill name: lowercase letters/digits/dashes, ≤32 chars, starts with a letter, no consecutive dashes. E.g., lobsters-frontpage, gh-issue-list, pypi-package-stats.
• 3–5 trigger phrases the agent should match against in future $qa --mode Report --module scrape calls. Mix the canonical phrase ("scrape lobsters frontpage") with paraphrases ("top posts on lobste.rs", "lobsters front page").
• The host (just the hostname, e.g. lobste.rs).

Then AskUserQuestion to confirm:

D<N> — Skill name + tier
Project/branch/task: codifying $qa --mode Report --module scrape "<intent>" as a browser-skill.
ELI10: Pick a short name we'll use to find this skill next time you say
something similar. Pick a tier — global means every project on this
machine sees it, project means just this repo.
Stakes if we pick wrong: bad name buries the skill in $B skill list;
wrong tier means future projects can't find it (or can find it when you
didn't want them to).
Recommendation: A — <proposed-name> at global tier — most scrape skills
generalize across projects.
Note: options differ in kind, not coverage — no completeness score.
A) Keep "<proposed-name>" at global tier — "${GSTACK_HOME:-$HOME/.gstack}"/browser-skills/<proposed-name>/  (recommended)
B) Keep "<proposed-name>" but at project tier — <project>/.gstack/browser-skills/<proposed-name>/
C) Rename it (free-form — say the new name)

Tier-shadowing check. Before showing the question, run $B skill list and check for an existing skill at the same name. If found, add to the question:

"Note: a skill named '' already exists. Picking the same name at a higher tier (project > global > bundled) shadows it; picking the same tier collides and will be refused at write time. Pick a different name to coexist."

Step 3 — Synthesize script.ts (D2)

Use only the final-attempt $B calls that produced the JSON the user accepted, plus the user's intent string. Drop:

• Failed selector attempts (the four selectors you tried before the working one)
• Unrelated $B commands from earlier turns
• All conversation prose, summaries, your own reasoning

The script imports the SDK from ./_lib/browse-client (a sibling copy, written in step 6) and exports a parser function so script.test.ts can exercise it against the bundled fixture without spinning up the daemon.

Mirror the bundled reference at browser-skills/hackernews-frontpage/script.ts:

import { browse } from './_lib/browse-client';

export interface Item { /* one row of the JSON output */ }
export interface Output { items: Item[]; count: number; }

const TARGET_URL = '<the URL the prototype used>';

export function parseFromHtml(html: string): Item[] {
  // Pure function: HTML in, parsed Item[] out. No $B calls.
  // Future fixture-replay tests call this directly.
}

if (import.meta.main) { await main(); }

async function main(): Promise<void> {
  await browse.goto(TARGET_URL);
  const html = await browse.html();
  const items = parseFromHtml(html);
  const output: Output = { items, count: items.length };
  process.stdout.write(JSON.stringify(output) + '\n');
}

The parser MUST be a pure function. If your prototype used multiple $B calls (e.g., goto + click "Next" + html), keep all of them in main() but extract the parsing into pure helpers. The fixture-replay tests in step 5 only exercise the pure parts.

Step 4 — Capture the fixture

$B goto "<TARGET_URL>"
$B html > /tmp/skillify-fixture-$$.html

The fixture filename inside the staged dir is fixtures/<host-with-dashes>-<YYYY-MM-DD>.html, where the date is today. E.g. fixtures/lobste-rs-2026-04-27.html.

Read the file you wrote, store its contents in a variable, and use it when staging in step 7.

Step 5 — Write script.test.ts

Mirror browser-skills/hackernews-frontpage/script.test.ts. The test must include at least one ★★ assertion — parsed output has the expected shape AND non-empty key fields — not a smoke ★ assertion. Smoke tests that only check parseFromHtml doesn't throw are insufficient.

import { describe, it, expect } from 'bun:test';
import * as fs from 'fs';
import * as path from 'path';
import { parseFromHtml } from './script';

describe('<name> parser', () => {
  const fixturePath = path.join(import.meta.dir, 'fixtures', '<host>-<date>.html');
  const html = fs.readFileSync(fixturePath, 'utf-8');
  const items = parseFromHtml(html);

  it('returns at least one item from the bundled fixture', () => {
    expect(items.length).toBeGreaterThan(0);
  });

  it('every item has the required shape', () => {
    for (const item of items) {
      expect(typeof item.<keyfield>).toBe('<keytype>');
      // ... assert on every required field
    }
  });
});

Step 6 — Resolve the canonical SDK path + read it

The canonical SDK lives at <gstack-install>/browse/src/browse-client.ts. The bundled-skill loader walks the install tree to find it; mirror that.

Resolve the gstack install dir. Two reliable signals (in order):

1. The bundled hackernews-frontpage skill — look at its tier path from $B skill list (the bundled row). The skill dir is <gstack-install>/browser-skills/hackernews-frontpage/, so the install dir is two dirname calls above its _lib/browse-client.ts.
2. The active gstack skills install at $GSTACK_ROOT/. Read the symlink target if it's a symlink, otherwise use the path directly.

Example (run as Bun, not bash, to avoid shell-redirect parsing issues):

import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';

function resolveSdkPath(): string {
  const candidates = [
    path.join(os.homedir(), '.claude', 'skills', 'gstack', 'browse', 'src', 'browse-client.ts'),
    // Add other install-dir candidates if your environment differs.
  ];
  for (const c of candidates) {
    try {
      const real = fs.realpathSync(c);
      if (fs.existsSync(real)) return real;
    } catch {}
  }
  throw new Error('Could not resolve canonical browse-client.ts');
}

const sdkContents = fs.readFileSync(resolveSdkPath(), 'utf-8');

Read the SDK contents into a variable. The staging step writes it as _lib/browse-client.ts byte-identical to the canonical. Phase 1 decision #4 — each skill is fully self-contained, no version drift possible.

Step 7 — Stage the skill (D3 atomic write)

Resolve the managed helper first with GSTACK_BROWSER_SKILL_WRITE=$($GSTACK_BIN/gstack runtime path browse/src/browser-skill-write.ts) and use that exact path. Construct an inline TypeScript snippet (or shell out to a small Bun one-liner) that calls:

import { stageSkill } from '<resolved GSTACK_BROWSER_SKILL_WRITE path>';

const stagedDir = stageSkill({
  name: '<name>',
  files: new Map([
    ['SKILL.md', skillMd],
    ['script.ts', scriptTs],
    ['script.test.ts', scriptTestTs],
    ['_lib/browse-client.ts', sdkContents],
    ['fixtures/<host>-<date>.html', fixtureHtml],
  ]),
});
console.log(stagedDir);

The SKILL.md content for <name> follows the Phase 1 frontmatter contract:

---
name: <name>
description: <one-line, what data this returns>
host: <hostname>
trusted: false       # agent-authored skills are untrusted by default
source: agent
version: 1.0.0
args: []             # extend if your script accepts --arg key=value
triggers:
  - <phrase 1>
  - <phrase 2>
  - <phrase 3>
---

# <Name> scraper

<2-3 sentences on what the script does, what URL it hits, and what
shape of JSON it returns. NO conversation context. NO chat fragments.
This is a durable on-disk artifact — keep it tight.>

## Usage

\`\`\`
$ $B skill run <name>
{ "items": [...], "count": N }
\`\`\`

Capture stagedDir (the path returned by stageSkill). You'll pass it to $B skill test next, then to commitSkill or discardStaged.

Step 8 — Run $B skill test against the staged dir

$B skill test "<name>" --dir "<stagedDir>"

If $B skill test does not yet accept --dir, fall back to invoking the test runner directly against the staged path:

( cd "<stagedDir>" && bun test script.test.ts )

If the test fails:

1. Read the test output. If the failure is a fixable parser bug, rewrite script.ts and script.test.ts (still inside the staged dir) and retry — at most twice. Show the diff to the user before each retry.

2. If still failing after two retries, OR the failure is an environmental issue (SDK import, daemon connection):

   import { discardStaged } from '<resolved GSTACK_BROWSER_SKILL_WRITE path>';
   discardStaged('<stagedDir>');
   

   Report the failure to the user, show them the staged script.ts for reference, and stop. No on-disk artifact.

Step 9 — Approval gate

Tests passed. Now ask the user before committing:

D<N> — Commit skill "<name>" at <resolved-tier-path>?
Project/branch/task: codified $qa --mode Report --module scrape "<intent>" — tests pass against fixture.
ELI10: The script ran clean against the snapshot we captured. Saying yes
moves the staged folder into "${GSTACK_HOME:-$HOME/.gstack}"/browser-skills/ where $qa --mode Report --module scrape
will find it next time. Saying no removes the staged folder and nothing
lands on disk.
Stakes if we pick wrong: yes commits an artifact you have to manually rm
later if you regret it ($B skill rm <name> --global). No throws away
~30s of synthesis work.
Recommendation: A — tests passed, the script is self-contained, this is
the productivity payoff for the prototype.
Note: options differ in kind, not coverage — no completeness score.
A) Commit it (recommended)
B) Look at the script first (I'll print SKILL.md + script.ts and re-ask)
C) Discard — don't commit

If the user picks B, print the staged SKILL.md and script.ts (NOT the fixture or _lib/), then re-ask the same A/B/C question (without B this time — they already saw it).

Step 10 — Commit (atomic) or discard

If the user approved:

import { commitSkill } from '<resolved GSTACK_BROWSER_SKILL_WRITE path>';
const dest = commitSkill({
  name: '<name>',
  tier: '<global|project>',  // from step 2 answer
  stagedDir: '<stagedDir>',
});
console.log(`Committed: ${dest}`);

If commitSkill throws "already exists" (tier-shadowing collision the user dismissed in step 2), report and ask whether to:

• Pick a different name (back to step 2)
• $B skill rm <name> then retry
• Discard

If the user rejected in step 9:

import { discardStaged } from '<resolved GSTACK_BROWSER_SKILL_WRITE path>';
discardStaged('<stagedDir>');

Report: "Discarded. No skill was written to disk."

Step 11 — Confirm + verify

After a successful commit, run one verification:

$B skill list | grep <name>
$B skill run <name>    # should match the JSON the prototype produced

If the post-commit run does not match the prototype output, something in synthesis drifted. Surface this to the user — they may want to $B skill rm <name> and retry. Do NOT silently roll back; the user deserves to see the discrepancy.

End the skill with one line: "Skill '' committed at . Future $qa --mode Report --module scrape calls matching '' will run in ~200ms."

---

Limits (be honest)

• Bun runtime required. The codified skill runs as a Bun process (bun run script.ts). Phase 1 design carry-over (Codex finding #7). Real fix lands in Phase 4 (self-contained binary or Node fallback). For now: the skill works on any machine that has gstack installed, which means it has Bun.
• Fixture-replay tests are point-in-time. When the target site rotates HTML, the fixture goes stale and the test passes against an outdated snapshot. Phase 4 will add fixture-staleness detection.
• Synthesis is best-effort. You're writing a script from your own conversation memory. If the prototype was complex (multi-page, JS hydration, lazy load) the codified script may need a hand-edit before it's reliable. The post-commit verify step catches obvious drift.
• Single-target only. One $B goto URL per skill. Multi-page crawls are out of scope — write a separate skill per target, or parameterize via args: if the URL pattern is regular.

What this skill does NOT do

• Codify match-path $qa --mode Report --module scrape results (matched skills are already codified)
• Codify mutating flows (those are /automate's job — Phase 2 P0)
• Run skills (that's $B skill run — codified skills are run via $qa --mode Report --module scrape's match path or directly)
• Edit existing skills ($EDITOR + the skill dir is the surface — $B skill show <name> finds the path)
• Tombstone or remove ($B skill rm)

Capture Learnings

If you discovered a non-obvious pattern, pitfall, or architectural insight during this session, log it for future sessions:

$GSTACK_BIN/gstack-learnings-log '{"skill":"skillify","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'

Types: pattern (reusable approach), pitfall (what NOT to do), preference (user stated), architecture (structural decision), tool (library/framework insight), operational (project environment/CLI/workflow knowledge).

Sources: observed (you found this in the code), user-stated (user told you), inferred (AI deduction), cross-model (both Claude and Codex agree).

Confidence: 1-10. Be honest. An observed pattern you verified in the code is 8-9. An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.

files: Include the specific file paths this learning references. This enables staleness detection: if those files are later deleted, the learning can be flagged.

Only log genuine discoveries. Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it.

Upstream judgment port: PR #679

Match the user language

User-language rule

Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy.

Upstream judgment port: PR #2030

Record only signal-bearing learnings

Signal-gated learning

Persist a learning only when the interaction contains a useful, reusable signal such as an explicit preference, correction, accepted recommendation, or rejected direction. Track helpful and harmful outcomes separately. Do not manufacture a learning merely because a workflow completed.