skills — repo conventions

The personal library contains eleven skills (autoconsultant, automake, consultant, consulting, copywriting, demo, first-principles, html, midwit, skill-issue, voice-mode), built on skill-creator (process authority: evals, baselines, viewer review, iteration, description optimization) and skill-issue (form authority: skills as SOPs—five types, nine sections, an admission gate, the bitter-lesson litmus, and vendor ceilings). The original eight were rebuilt in ~/dev/skills-new and ported here wholesale.

Layout

• skills/<name>/ — shipping surface. Everything committed here reaches installers verbatim (npx skills add has no .skillignore). Nothing goes in a skill dir except what installers should receive.
• evals/<name>/ — committed eval sources for that skill: prompts (evals.json), assertions, fixtures (fixtures/).
• evals/<name>/runs/ and skills/*-workspace/ — generated evidence (run output, transcripts, benchmarks, viewer HTML). Gitignored, never committed.

Process

• Skills are built with the vanilla skill-creator loop: with-skill vs no-skill baseline runs, graded assertions, eval viewer review, iterate until the client is happy / feedback is empty / progress stalls; then description optimization (trigger evals, run_loop.py), whose best_description is applied verbatim.
• skill-issue governs form: every skill is one of five SOP types and carries nine ordered sections; admission and every body line pass the bitter-lesson gate, with overflow to references/scripts and vendor ceilings. Existing skills predate this standard and are not retrofitted unless explicitly scoped.
• agentskills validate is not available on npm → the shipping gate is a recorded manual frontmatter check per skill (name/format only; the description field is owned by the trigger-eval optimizer and is never rewritten by hand).

Declared deviations from skill-creator's default

evals.json, assertions, and fixtures live in evals/<name>/, never inside skills/<name>/. skill-creator's default puts evals/ inside the skill folder, but this repo's installer ships everything committed under skills/<name>/ verbatim, so eval material there would ship to all agents.

Description optimization may replace skill-creator's stock run_loop.py when that runner requires a prohibited model family. The substitute keeps the same frozen-query, train/held-out, repeated-evaluation, best_description-verbatim contract, records the exact allowed models, and never shells out to the prohibited runner. These are the only process deviations; everything else follows skill-creator as written.

Baseline purity

No-skill baseline arms run with a prompt that forbids invoking any installed skill — a "no-skill" run could otherwise silently lean on an installed sibling (or an earlier rebuilt skill from this repo) and corrupt the prove-need evidence. With-skill arms MAY use installed siblings (that is the real composed environment being dogfooded) and are graded consistently on that basis. The grader checks run transcripts for skill invocations and flags any contaminated baseline run.

Interactive flows in evals

Eval executors are headless one-shot subagents, but several of these skills (consultant and autoconsultant above all) ask one question at a time and gate on approvals. Eval prompts therefore embed the complete scenario plus a scripted "user replies" block the subagent treats as the user's answers, in order. Assertions verify the skill asked and gated (the contract), not that live turns occurred. Client sign-off of test prompts covers the reply script.

Live-state isolation

Several of these skills write durable state outside a repo (consultant → ~/.consultant/, html → ~/.html/, others as discovered at intent time). Eval runs never touch those live directories. Every run redirects the skill's state root into its own run directory (e.g. <workspace>/iteration-N/<eval>/<arm>/outputs/), via the environment or explicit prompt instruction, and operates only there. Committed fixtures under evals/<name>/fixtures/ are pristine and read-only; runs copy them into the run directory first. Fixtures are plain directories — no nested .git; where a skill's behavior needs a git repo (automake's git-backed candidates), the run prompt has the subagent git init its copy.

Every eval subagent saves a run transcript (transcript.md in its run directory) — the grader's contamination check and the viewer depend on it. Name eval directories eval-<ID>-<descriptive-name> (satisfies skill-creator's descriptive-names instruction and aggregate_benchmark.py's eval-* glob).

Install

After each skill passes its done-gate:

npx skills add /Users/eliasstravik/dev/skills --skill <name> -g

-g/--global = user-level install; without it the CLI installs project-level.