v0.7.0

Fixed

• quick_validate.py / package_skill.py no longer require PyYAML at runtime. They imported PyYAML, which Cowork's container image lacks and its default-deny egress can't pip install — so both crashed (or the agent fell back to hand-validation) when the skill ran under Cowork. Replaced with a stdlib-only scripts/frontmatter.py parser covering the frontmatter YAML subset (scalars, nested mappings, block/flow sequences, block scalars) and rejecting exotic constructs (anchors/aliases/tags/merge/multi-doc) with a clear error. Behavior is identical across runtimes because there's a single parser; a differential test (tests/test_frontmatter.py) keeps it aligned with yaml.safe_load. PyYAML is now a test-only dependency. quick_validate exit code 2 is retired to "reserved".

Added

• scripts/check_portability.py — a stdlib-only cross-runtime portability linter. Flags constructs that break on a skill's target runtime: over-cap description, subagent use (absent on Claude.ai), claude CLI use (absent on Claude.ai), browser/server assumptions (no display in Cowork/Claude.ai), and third-party Python imports in bundled scripts (Cowork's sandbox lacks them and can't pip install). --target claude-code|claude-ai|cowork|all, --json, --strict.
• harness/ — a cowork-harness dogfood suite that regression-tests this skill under Claude Cowork's runtime, plus a token-free CI lane (.github/workflows/harness.yml).

v0.6.0

Changed

• Eval definitions now live outside the skill directory. SKILL.md and references/schemas.md previously told authors to save evals/evals.json inside the skill directory (inherited verbatim from the upstream Anthropic skill-creator, whose schemas.md still says "within the skill directory"). Plugin/marketplace installs copy the whole skill directory into every client, so an eval file inside it shipped the answer key (prompts + expected_output + assertions) to runtime and added dead weight to every install. New convention, split by lifecycle: eval definitions → <skill-name>-evals/ committed sibling (regression suite; CI-run if the skill has a repo); eval results → <skill-name>-workspace/ gitignored sibling (ephemeral); the skill directory → pure runtime content only. package_skill.py's root evals//tests/ exclusion is retained as belt-and-suspenders. See references/schemas.md → "Where evals live".

v0.5.0

Fixed

• aggregate_benchmark.py: benchmark.json runs array was corrupted by loop-variable shadowing (regression introduced alongside the 0.4.1 runs_per_configuration fix) — the viewer's Benchmark tab silently showed empty data. Also: IndexError on stray non-eval-N directories, token counts no longer fall back to character counts, tokens are read from grading.json timing AND timing.json, pass-rate delta is now percentage points, and partially-graded evals produce a loud warning.
• run_eval.py: parallel workers no longer share .claude/commands/ — each run gets an isolated temp project root, eliminating cross-contaminated trigger detection that biased optimization. Subprocess failures and no-output timeouts are now reported as errors and excluded from trigger rates instead of being scored as "did not trigger"; if every run errors the CLI exits 1.
• run_loop.py --holdout 0 no longer crashes writing the live report; tiny eval sets that would produce an empty train split now fail fast with guidance.
• Eval viewer: clicking OK after Submit no longer overwrites the completed feedback.json; auto-save status is honest in static mode; run sorting no longer crashes on mixed eval_id presence; embedded JSON escapes all < (covers <!--/<script, not just </script>); grader evidence is attribute-escaped.
• quick_validate.py rejects empty/whitespace name and description, and enforces name-matches-folder.
• package_skill.py excludes tests/ from artifacts, skips symlinks instead of dereferencing them, and prints a friendly error when run as a plain script. The release workflow now builds through it, so exclusions apply to published zips.
• Agent contracts: grader copies timing.json verbatim (incl. total_tokens — real token counts now reach benchmarks); comparator declares its output path and counterbalances position bias; analyzer notes are merged into benchmark.json via the new --notes flag.
• Docs: packaging is unconditional (no longer gated on the Claude.ai-only present_files tool), static-mode feedback documentation matches viewer behavior, schemas.md documents all four configuration strings and eval_metadata.json, run_loop cwd requirement stated, license is a top-level frontmatter field, SKILL.md is back under 500 lines (environment + description-optimization details moved to references/).

Added

• aggregate_benchmark.py --notes <file> merges analyst notes into benchmark.json.
• tests/: coverage for aggregate_benchmark, generate_report, run_eval scoring, run_loop split, package_skill planning, generate_review — and CI now runs the suite.
• docs/DEVELOPMENT.md: tracked developer reference (was only in the gitignored CLAUDE.md).

v0.4.2

Fixed

• aggregate_benchmark.py: warns when an eval directory has no grading.json in any config subdirectory. Previously such evals were silently skipped — common when a grader run is interrupted partway through, leaving some evals graded and others not. The benchmark would then cover only the evals that finished, with no signal that data was missing. Now emits a single warning listing every skipped eval directory by name so partial-run silent data loss is visible.

v0.4.1

Fixed

• aggregate_benchmark.py: runs_per_configuration is now computed from data instead of hardcoded to 3. The metadata field claims a per-(eval, config) run count; previously benchmark.md always rendered "3 runs each per configuration" regardless of how many grading.json files actually existed. Now derives the value by counting runs per (eval_id, configuration) pair.
• aggregate_benchmark.py: silent-zeroing of pass rates is now a loud warning. When a grading.json is malformed or schema-divergent (e.g., missing the top-level summary object documented in references/schemas.md), the script previously defaulted every metric to 0 with no signal. Now emits a clear warning to stderr identifying the file and the missing key, so users see the failure mode immediately instead of debugging mysterious 0% pass rates.

v0.4.0

Added

• Designing Scripts for Agent Use — new section in references/official-guide-patterns.md covering the conventions that make a bundled script usable to an agent rather than just to a human: non-interactive, --help-documented, structured output (JSON/CSV), helpful error messages, meaningful exit codes, idempotency, dry-run support, predictable output size, and inline dependencies (PEP 723 etc.). Pointer added to SKILL.md.
• Dual-purpose script framing in SKILL.md: the same validate_X.py/smoke_test_X.sh users run can also serve as an eval-time grader assertion (and vice versa). Made explicit in both the grading step and the convergence-signal section.
• Script-when / Instruct-when first-pass heuristic in SKILL.md's draft-time design step, with an explicit note that the strongest signal still comes downstream from convergence in eval runs.
• scripts/requirements.txt declaring pyyaml so the validator's only non-stdlib dependency is documented.

Changed

• quick_validate.py is now agent-friendly. Converted to argparse (was hand-rolled sys.argv), added --json mode ({"valid": …, "error": …, "skill_path": …}), graceful ImportError for missing PyYAML (exit 2 instead of traceback), and a Path.exists() pre-check that fires distinct exit code 3 for "skill directory not found" vs. 1 for validation failure. Exit codes are documented in --help epilog.
• package_skill.py is now agent-friendly. Converted to argparse, added --dry-run (lists files and target path without writing the zip), --json mode (structured output replacing emoji prose), and a stderr warning when overwriting an existing artifact. Exit codes documented in --help epilog.
• Consistent --help epilogs across all argparse-using scripts (aggregate_benchmark, generate_report, improve_description, run_eval, run_loop) — every script now documents its example invocation and exit-code semantics.

v0.3.0

Added

• Portable skill spec support. quick_validate.py now accepts the full agentskills.io cross-host spec (name, description, license, compatibility, metadata, allowed-tools) plus all documented Claude-specific fields (when_to_use, model, effort, agent, paths, hooks, shell, context, disable-model-invocation, user-invocable, argument-hint) plus undocumented-but-functional (version, arguments, created_by). Each field is type-checked; values outside documented ranges (e.g. context other than 'fork', bad effort keywords, non-boolean disable-model-invocation) are rejected with specific error messages.
• Combined-length check. Validator rejects description + when_to_use > 1,536 characters — Claude Code v2.1.116 truncates skill-listing entries at that threshold, so catching it pre-flight prevents silent truncation at runtime.
• First unit test file for the validator (tests/test_quick_validate.py, 17 tests) covering field acceptance, type rejection, boundary cases, and the new combined-length check.
• Portability-first docs. SKILL.md frontmatter guidance now teaches the portable core first and flags Claude-specific fields as optional extensions. New "Runtime Mechanics & Gotchas (Claude Code)" section in official-guide-patterns.md documents the ~8 KB listing budget, ~20-char collapse threshold, 1,536-char per-entry truncation, chokidar depth-2 live-reload, gitignore-syntax paths: matching, and MCP skill carve-outs.
• Listing-collapse troubleshooting entry for the failure mode where every installed skill collapses to name-only when any skill's share of the listing budget drops below ~20 chars.
• Description optimizer: --target-length (default 500) — soft target surfaced to the improver. Selection uses length-aware tuple-keys so ties break toward the shortest description. Hard cap of 1,024 chars (agentskills.io spec) is preserved.
• Description optimizer: --plateau-patience (default 2) — stops the loop early if the test score hasn't improved in N consecutive iterations, instead of burning all iterations appending verbiage.
• Per-attempt char counts surfaced in the improver's history view, so the model can see the length-cost trajectory and prefer tighter rewrites.

Changed

• Description optimizer prompt now explicitly frames the portability constraint (output must stand alone for hosts that only read description) and explains the Claude listing-budget collapse mode — so the improver stops drifting toward bloated 1,024-char descriptions.
• run_loop verbose output now includes the length trajectory of all attempted descriptions alongside the score trajectory.
• Selection tie-break: when test scores tie, the shorter description wins.

Fixed

• Validator no longer rejects legitimate SKILL.md frontmatter. The previous allowlist was 10 fields; the new one is 19 (all portable spec + all documented Claude-specific + all undocumented-but-functional).

Portability notes

• Optimizer still emits a single description field. It never splits into description + when_to_use, so output stays cross-host portable.
• when_to_use is supported but never recommended as the default — the portable pattern remains "everything in description."

v0.2.1

Fixed

• quick_validate.py now accepts the four frontmatter fields documented in official-guide-patterns.md that it previously rejected as "unexpected": disable-model-invocation, context, argument-hint, and user-invocable. Skills using these fields can now be validated and packaged successfully.
• Added value validation for the newly-recognized fields: context must be 'fork'; disable-model-invocation and user-invocable must be booleans; argument-hint must be a string under 200 characters.

v0.2.0

Added

• "Script vs. Instruct" decision framework in official-guide-patterns.md — when to offload work to bundled scripts vs. keep as SKILL.md instructions, with concrete examples and a decision walkthrough.
• Expanded "Store Scripts & Let Claude Compose" section with restored Thariq example and "Why Offload to Scripts" rationale (context window efficiency, reliability, speed, auditability).
• Brief "Script vs. Instruct" pointer in SKILL.md design phase so guidance surfaces at the right workflow moment.
• Cross-reference from the improve phase's "repeated work" observation to the new decision framework.

v0.1.5

Fixed

• Eval viewer "Submit All Reviews" no longer causes a blank white page in Cowork. The blob URL download (a.click()) navigated Cowork's embedded viewer instead of downloading. Removed the download attempt in static mode — the copyable JSON textarea is the reliable feedback path.