baldart 4.81.0 → 4.83.0

package/framework/.claude/skills/new/references/implement.md

@@ -113,59 +113,58 @@
    Design file: [path from card's links.design field]
    Design source: [path from card's links.design_src field, if present]
 
-   **PRIMARY — finished source code (`links.design_src` / `mockups/_src/`).**
-   When the card carries `links.design_src`, or the PRD's `mockups/_src/` holds
-   the screen's archived `.jsx`/`.css`/tokens (a Claude Design export pulled at
-   `/prd` time), THAT CODE is the fidelity source — not the pixels. `Read` those
-   files and BUILD FROM THEM per `framework/.claude/agents/ui-expert.md` §
-   "Design Reference — When the mockup is finished CODE": reuse-first (map the
-   source's token refs / classes to the registry primitives), copy structure /
-   spacing / `@keyframes` / `@media` exactly, introduce a new component only via
-   `/ds-new`. The image branch below is then a SECONDARY visual cross-check, not
-   the source of truth. **You MUST declare** which `mockups/_src/` files you read,
-   the source symbols/classes you reuse, and the registry primitives you map them
-   to (declaration gate below — the orchestrator grounds it against disk).
-
-   **Load the mockup image into your context — branch on the file type:**
-   - If `links.design` resolves to an IMAGE (`.png` / `.jpg` / `.jpeg` /
-     `.webp` / `.pdf`, or the card points at a `mockups/*.png` canonical path):
-     you are multimodal — **`Read` the mockup image file path directly**. `Read`
-     renders the image visually into your context (the native multimodal
-     mechanism). The mockup's PIXELS are the fidelity target: study layout,
-     spacing, hierarchy, density, color, and the relative position of every
-     region. Do NOT implement from the filename or a textual guess — you MUST
-     actually load and look at the image. (On a non-multimodal tool the `Read`
-     degrades to no-op text; fall back to the structured fields below.)
-   - If `links.design` is an `.html` file: **Read the design.html file** and use
-     it as the visual reference. **If that file does not exist** (a legacy
-     mockup-only card that points at a `design.html` which was never generated),
-     fall back: look under the PRD's `mockups/` dir (sibling of the `links.design`
-     path) for the screen's PNG/JPG and `Read` that image instead — do not proceed
-     with no visual reference.
-
-   Use it as the **visual reference** for your implementation (layout, spacing,
-   hierarchy, copy). The design was approved by the user — your implementation
-   MUST match its appearance.
-
-   **Structured design intent (when present on the card).** The image shows the
-   static look at one viewport; these fields cover what a single image cannot:
-   - `component_bindings[].props` / `variant` — the exact props/variant each
-     region must use (e.g. `SectionHeader {depth: 0}`, `DataTable {density:
-     comfortable}`). Implement them verbatim; do not eyeball a variant.
-   - the card's responsive acceptance criteria — breakpoint behaviour the
-     single-viewport mockup does not show (e.g. "≤640px: table collapses to
-     card-list"). These are testable ACs, not optional polish.
-
-   **The mockup is a visual reference, NOT a license to re-create components.**
-   When the card carries `component_bindings` (the `/prd` Component Reconciliation
-   map — see `agents/card-schema.md`), THAT map is authoritative over *which
-   component each region IS*: a region bound `action: reuse → SectionHeader` MUST
-   be implemented by reusing `SectionHeader`, even if the mockup's pixels look like
-   a fresh header. Honor the binding over any contrary reading of the mockup. Only
-   `action: new` entries (confirmed with the user at `/prd` time) may introduce a
-   component. A card with UI scope and `features.has_design_system: true` but NO
-   `component_bindings` → run the cascade below as your own reconciliation before
-   writing code (do not assume a mockup affordance is a new component).
+   **DELEGATION GATE — mockup→code is owned by `/ui-implement` (since v4.82.0).**
+   When the `/ui-implement` skill is available AND the card has `links.design` /
+   `links.design_src`, the orchestrator DELEGATES this card's mockup→code
+   **implement + fidelity verify** to `/ui-implement` in programmatic mode
+   (contract: `framework/.claude/skills/ui-implement/references/integration.md`).
+   The skill is the SSOT of the input-type build playbook (Claude Design link /
+   finished-code / image / HTML) and folds in Phase 2.6 `/e2e-review`. On delegation: **skip the
+   coarse briefing below AND Phase 2.6 for this card** (the skill already ran the
+   fidelity verify), consume its COMPACT JSON, then resume the normal per-card
+   cluster on the resulting diff (Phase 2.55 Simplify → **skip Phase 2.6** which
+   the skill already ran → Phase 3 doc / 3.5 QA / 3.7 Codex — the skill's scope is
+   **fidelity only**, no review hole). The `ui-expert` registry-first cascade +
+   Post-Intervention Coherence below STILL apply — the skill enforces the same
+   SSOTs. **Coarse inline fallback** (skill unavailable / Codex / older install):
+   use the briefing below + Phase 2.6 as before; the prose here stays the SSOT
+   fallback (delegate-or-else-inline).
+
+   **Coarse fallback — build workflow by input type.** The full SSOT is
+   `framework/.claude/skills/ui-implement/references/playbook.md` +
+   `framework/.claude/agents/ui-expert.md` § "Design Reference — When the mockup
+   is finished CODE":
+   - **Finished source code** (`links.design_src` / `mockups/_src/*.jsx`,`*.css`)
+     is the PRIMARY fidelity source, NOT the pixels: `Read` it and BUILD FROM IT
+     reuse-first (map source token refs / classes to registry primitives, copy
+     structure / spacing / `@keyframes` / `@media` exactly, new component only via
+     `/ds-new`). **You MUST declare** the `mockups/_src/` files you read, the
+     source symbols/classes you reuse, and the registry primitives you map them to
+     (grounded at Step 7b).
+   - **Image** (`.png` / `.jpg` / `.jpeg` / `.webp` / `.pdf`, or a `mockups/*.png`
+     canonical path): you are multimodal — **`Read` the image path directly** so
+     the PIXELS render into context; they are the fidelity target (layout, spacing,
+     hierarchy, density, color, region positions). Do NOT build from the filename.
+     (Non-multimodal tool → the `Read` degrades to no-op; fall back to the
+     structured fields below.)
+   - **HTML** (`.html`): `Read` it as the visual reference. If missing, look under
+     the PRD's `mockups/` dir for the screen's PNG/JPG and `Read` that instead — do
+     not proceed with no visual reference.
+
+   The design was approved by the user — your implementation MUST match its
+   appearance AND its responsive acceptance criteria (breakpoint behaviour a
+   single-viewport image does not show are testable ACs, not optional polish).
+
+   **`component_bindings` are authoritative over the mockup.** When the card
+   carries `component_bindings` (the `/prd` Component Reconciliation map — see
+   `agents/card-schema.md`), a region bound `action: reuse → SectionHeader` MUST be
+   implemented by reusing `SectionHeader`, even if the pixels look like a fresh
+   header. Honor the binding over any contrary reading; implement
+   `component_bindings[].props` / `variant` verbatim (do not eyeball a variant).
+   Only `action: new` entries (confirmed at `/prd` time) may introduce a component.
+   UI scope + `features.has_design_system: true` but NO `component_bindings` → run
+   the cascade below as your own reconciliation before writing code (do not assume
+   a mockup affordance is a new component).
 
    ### i18n constraint (include when `features.has_i18n: true`)
    No user-facing string may be hardcoded. Externalize every label through the

package/framework/.claude/skills/new/references/review-cycle.md

@@ -158,6 +158,22 @@ The skill replaces the previous advisory pair (legacy Phase 2.6 E2E testing
 and Phase 2.7 visual design review). It runs by default on every UI card,
 auto-skips on backend-only cards, and BLOCKS the commit on gating findings.
 
+> **Delegated cards skip this phase (since v4.82.0).** When Phase 2 delegated this
+> card's mockup→code implement+verify to `/ui-implement` (its delegation gate in
+> `implement.md` fired), `/ui-implement` ALREADY ran `/e2e-review` internally as
+> its self-verify step. Do NOT invoke `/e2e-review` again here — consume the
+> skill's COMPACT JSON (same `status` contract as below) and apply the gating table
+> directly. Re-invoking would double the fidelity pass. Log `"e2e-review: SKIP
+> (delegated to /ui-implement — verdict from the skill)"`.
+>
+> **Drift note (maintainers):** `/ui-implement` folds Phase 2 Design-Reference
+> build + this Phase 2.6 into one skill for a UI card; the coarse fallback prose in
+> `implement.md` + this phase stays the SSOT for the non-delegated path. `new2.js`
+> keeps the INLINE path (no delegation) in this release — full parity (delegating
+> off-context via `workflow()`) is a follow-up after the context-economy
+> measurement. When you change this phase's gating or the mockup cascade, keep
+> `ui-implement/references/integration.md` in sync.
+
 > **Route-independent, self-contained verification (since v4.78.0).** This card verifies
 > its **OWN** UI surface — it does NOT defer fidelity to a downstream card. `/e2e-review`
 > now runs a **route-free structural pass** (Phase 2.7, `markup-fidelity-verifier`: the

package/framework/.claude/skills/new2/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — new2
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/new2/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: new2
 effort: high
+version: 1.0.0
 description: >
   EXPERIMENTAL workflow-hosted variant of /new (A/B testing). Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background

package/framework/.claude/skills/overlay/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — overlay
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/overlay/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: overlay
 effort: medium
+version: 1.0.0
 description: "Guided author of .baldart/overlays/ — the per-project customisation layer for BALDART skills, agents, and commands. Use when the user says /overlay, 'customizza skill', 'modifica agente upstream', 'personalizza comando', 'crea overlay', 'extend skill X', 'override agent Y', 'overlay drift', or when the framework-edit-gate hook blocked an edit and pointed here. The skill walks the user through choosing the right canal (skill / agent / command), scaffolds the overlay with correct frontmatter and section markers via `npx baldart overlay scaffold`, validates the merge via `npx baldart overlay validate`, and surfaces drift via `npx baldart overlay drift`. Never edits `.framework/` directly and never re-implements the merger logic — the CLI is the source of truth."
 contamination_scan: skip
 ---

package/framework/.claude/skills/playwright-skill/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — playwright-skill
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/playwright-skill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: playwright-skill
 effort: medium
+version: 1.0.0
 description: E2E browser testing with Playwright Test CLI. Write .spec.ts files in tests/e2e/, run via `npm run test:e2e`. Supports headed mode, debug, UI mode, filtering, retries, screenshots, and trace on failure. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing.
 ---
 

package/framework/.claude/skills/prd/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — prd
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/prd/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: prd
 effort: high
+version: 1.0.0
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 

package/framework/.claude/skills/prd-add/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — prd-add
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/prd-add/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: prd-add
 effort: medium
+version: 1.0.0
 description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
 ---
 

package/framework/.claude/skills/remotion-best-practices/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — remotion-best-practices
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/remotion-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: remotion-best-practices
 effort: medium
+version: 1.0.0
 description: Best practices for Remotion - Video creation in React
 metadata:
   tags: remotion, video, react, animation, composition

package/framework/.claude/skills/seo-audit/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — seo-audit
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/simplify/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — simplify
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/simplify/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: simplify
 effort: medium
+version: 1.0.0
 description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Use when completing a coding task, after implementation, or when the user says /simplify. Covers deduplication (exact/near/inline), code quality patterns, and performance.
 ---
 

package/framework/.claude/skills/skill-creator/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — skill-creator
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.0.0 — 2026-07-01
+
+- Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/skill-creator/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: skill-creator
 effort: medium
+version: 1.0.0
 description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
 license: Complete terms in LICENSE.txt
 ---
@@ -116,11 +117,16 @@ A skill should only contain essential files that directly support its functional
 - README.md
 - INSTALLATION_GUIDE.md
 - QUICK_REFERENCE.md
-- CHANGELOG.md
 - etc.
 
 The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
 
+> **BALDART override — `CHANGELOG.md` IS required.** Every BALDART skill ships a
+> per-skill `CHANGELOG.md` (the one exception to the rule above). It is deliberately
+> a SEPARATE file, NOT a section of `SKILL.md`, so the version history never burns
+> context when the skill is loaded. Together with the `version:` frontmatter key it
+> is the canonical structure — see [references/skill-structure.md](references/skill-structure.md).
+
 ### Progressive Disclosure Design Principle
 
 Skills use a three-level loading system to manage context efficiently:
@@ -280,11 +286,11 @@ scripts/init_skill.py <skill-name> --path <output-directory>
 The script:
 
 - Creates the skill directory at the specified path
-- Generates a SKILL.md template with proper frontmatter and TODO placeholders
-- Creates example resource directories: `scripts/`, `references/`, and `assets/`
-- Adds example files in each directory that can be customized or deleted
+- Generates a SKILL.md template with proper frontmatter (`name` + `effort` + `version`) and TODO placeholders
+- Generates a per-skill `CHANGELOG.md` (canonical structure — see [references/skill-structure.md](references/skill-structure.md))
+- Does NOT scaffold empty `scripts/` / `references/` / `assets/` dirs — add them on demand only when the skill needs them (no placeholder noise)
 
-After initialization, customize or remove the generated SKILL.md and example files as needed.
+After initialization, complete the generated SKILL.md + CHANGELOG.md and add resource folders as needed.
 
 ### Step 4: Edit the Skill
 
@@ -305,7 +311,7 @@ To begin implementation, start with the reusable resources identified above: `sc
 
 Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
 
-Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
+Add only the resource directories the skill actually needs (`scripts/` executables, `references/` on-demand docs, `assets/` output templates). The initializer no longer scaffolds empty placeholder dirs — the canonical structure is `SKILL.md` + `CHANGELOG.md` plus whatever folders the skill genuinely uses. See [references/skill-structure.md](references/skill-structure.md).
 
 #### Update SKILL.md
 
@@ -313,16 +319,18 @@ Any example files and directories not needed for the skill should be deleted. Th
 
 ##### Frontmatter
 
-Write the YAML frontmatter with `name`, `description`, and `effort`:
+Write the YAML frontmatter with `name`, `description`, `effort`, and `version`:
 
 - `name`: The skill name
 - `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
   - Include both what the Skill does and specific triggers/contexts for when to use it.
   - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
+  - Include no angle brackets (`<` / `>`) — the loader/validator rejects them.
   - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
 - `effort`: The skill's baseline reasoning effort — one of `low | medium | high | xhigh | max`. Pick it by the skill's dominant cognitive load per the tiering rubric in `framework/agents/effort-protocol.md` (routine/lookup → `low`; standard authoring/review → `medium`; deep reasoning/orchestration → `high`). When in doubt, default to `medium` and let the user escalate per-run via the inline override.
+- `version`: The skill's own SemVer (`MAJOR.MINOR.PATCH`), starting at `1.0.0`. Bump it whenever you change the skill and add a matching `CHANGELOG.md` entry — this is how skills evolve deliberately over time, independent of the framework version. See [references/skill-structure.md](references/skill-structure.md).
 
-Beyond `name`, `description`, and `effort`, do not include other fields in YAML frontmatter.
+Beyond `name`, `description`, `effort`, and `version`, do not include other fields in YAML frontmatter (`license` / `metadata` are tolerated for third-party skills).
 
 Then paste the `## Effort` body block from `framework/templates/skill-effort.snippet.md` right after `## Project Context` (or after the title if the skill has no Project Context header), so the skill honors the inline `effort=<level>` override. See `framework/agents/effort-protocol.md` for the parsing contract.
 

package/framework/.claude/skills/skill-creator/references/skill-structure.md

@@ -0,0 +1,81 @@
+# Canonical skill structure (BALDART)
+
+The SSOT for how a BALDART skill is laid out and versioned. Every skill under
+`framework/.claude/skills/<name>/` follows this — `init_skill.py` scaffolds it and
+`quick_validate.py` warns on drift.
+
+## Layout
+
+```
+framework/.claude/skills/<name>/
+├── SKILL.md          # REQUIRED — the skill (frontmatter + body). Loaded into context on trigger.
+├── CHANGELOG.md      # REQUIRED — per-skill version history. NOT loaded with SKILL.md.
+├── references/       # OPTIONAL — docs loaded on demand (playbooks, schemas, contracts).
+├── assets/           # OPTIONAL — output templates/files, never loaded into context.
+└── scripts/          # OPTIONAL — executables (run, not read).
+```
+
+**`SKILL.md` and `CHANGELOG.md` are mandatory. The three folders are created ONLY
+when the skill needs them** — no empty placeholder dirs (that was upstream
+`init_skill.py` noise, now removed). A single-file skill (just `SKILL.md` +
+`CHANGELOG.md`) is perfectly canonical.
+
+## Frontmatter (required keys)
+
+```yaml
+---
+name: <kebab-case>            # matches the directory name
+effort: medium               # low | medium | high | xhigh | max  (effort-protocol.md)
+version: 1.0.0               # the skill's OWN SemVer
+description: >               # triggers + what/when; NO angle brackets
+  ...
+---
+```
+
+Order: `name` → `effort` → `version` → `description`. `license` / `metadata` are
+tolerated only on imported third-party skills; do not add other keys.
+
+## Body headers (in order, when applicable)
+
+1. `## Project Context` — when the skill reads `baldart.config.yml`
+   (`framework/templates/skill-project-context.snippet.md`).
+2. `## Effort` — the inline-override block
+   (`framework/templates/skill-effort.snippet.md`).
+3. The skill's own workflow / playbook / reference sections.
+
+## Versioning + CHANGELOG discipline
+
+- **Why a separate `CHANGELOG.md`?** `SKILL.md` is loaded into context every time
+  the skill triggers; a changelog inside it would burn tokens on every invocation
+  for history the runtime never needs. Keeping it in a sibling file means the
+  history is there for a human/maintainer but costs zero runtime context.
+- **`version` is the skill's OWN SemVer**, independent of the framework `VERSION`.
+  It lets a skill evolve deliberately and be diffed over time.
+  - **PATCH** — wording/clarity fix, no behaviour change.
+  - **MINOR** — added a capability, reference, or option (backwards-compatible).
+  - **MAJOR** — changed the invocation contract, removed a step, or otherwise broke
+    a caller's expectations.
+- **Every change to a skill bumps `version` AND adds a `CHANGELOG.md` entry** in the
+  same edit. The framework `CHANGELOG.md` (repo root) still records the release; the
+  per-skill one records the skill's own line of evolution.
+
+### `CHANGELOG.md` format (Keep-a-Changelog-lite)
+
+```markdown
+# Changelog — <name>
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+
+## 1.1.0 — 2026-08-15
+- Added: <what changed>.
+
+## 1.0.0 — 2026-07-01
+- Baseline.
+```
+
+## Validation
+
+`python framework/.claude/skills/skill-creator/scripts/quick_validate.py <skill-dir>`
+returns valid but WARNS when `version` / `effort` / `CHANGELOG.md` are missing
+(non-fatal, for backwards-compat with pre-convention skills). New skills must be
+warning-free.

package/framework/.claude/skills/skill-creator/scripts/init_skill.py

@@ -17,11 +17,18 @@ from pathlib import Path
 
 SKILL_TEMPLATE = """---
 name: {skill_name}
-description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+effort: medium
+version: 1.0.0
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it. No angle brackets.]
 ---
 
 # {skill_title}
 
+<!-- BALDART canonical structure: keep `name` + `effort` + `version` in frontmatter,
+     ship a sibling CHANGELOG.md (already created), and paste the `## Project Context`
+     + `## Effort` headers from framework/templates/*.snippet.md right after the intro.
+     See framework/.claude/skills/skill-creator/references/skill-structure.md. -->
+
 ## Overview
 
 [TODO: 1-2 sentences explaining what this skill enables]
@@ -102,87 +109,14 @@ Files not intended to be loaded into context, but rather used within the output
 **Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
 """
 
-EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
-"""
-Example helper script for {skill_name}
 
-This is a placeholder script that can be executed directly.
-Replace with actual implementation or delete if not needed.
+CHANGELOG_TEMPLATE = """# Changelog — {skill_name}
 
-Example real scripts from other skills:
-- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
-- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
-"""
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
-def main():
-    print("This is an example script for {skill_name}")
-    # TODO: Add actual script logic here
-    # This could be data processing, file conversion, API calls, etc.
+## 1.0.0 — TODO-DATE
 
-if __name__ == "__main__":
-    main()
-'''
-
-EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
-
-This is a placeholder for detailed reference documentation.
-Replace with actual reference content or delete if not needed.
-
-Example real reference docs from other skills:
-- product-management/references/communication.md - Comprehensive guide for status updates
-- product-management/references/context_building.md - Deep-dive on gathering context
-- bigquery/references/ - API references and query examples
-
-## When Reference Docs Are Useful
-
-Reference docs are ideal for:
-- Comprehensive API documentation
-- Detailed workflow guides
-- Complex multi-step processes
-- Information too lengthy for main SKILL.md
-- Content that's only needed for specific use cases
-
-## Structure Suggestions
-
-### API Reference Example
-- Overview
-- Authentication
-- Endpoints with examples
-- Error codes
-- Rate limits
-
-### Workflow Guide Example
-- Prerequisites
-- Step-by-step instructions
-- Common patterns
-- Troubleshooting
-- Best practices
-"""
-
-EXAMPLE_ASSET = """# Example Asset File
-
-This placeholder represents where asset files would be stored.
-Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
-
-Asset files are NOT intended to be loaded into context, but rather used within
-the output Claude produces.
-
-Example asset files from other skills:
-- Brand guidelines: logo.png, slides_template.pptx
-- Frontend builder: hello-world/ directory with HTML/React boilerplate
-- Typography: custom-font.ttf, font-family.woff2
-- Data: sample_data.csv, test_dataset.json
-
-## Common Asset Types
-
-- Templates: .pptx, .docx, boilerplate directories
-- Images: .png, .jpg, .svg, .gif
-- Fonts: .ttf, .otf, .woff, .woff2
-- Boilerplate code: Project directories, starter files
-- Icons: .ico, .svg
-- Data files: .csv, .json, .xml, .yaml
-
-Note: This is a text placeholder. Actual assets can be any file type.
+- Skill introdotta. [TODO: 1-line summary of what it does.]
 """
 
 
@@ -233,39 +167,30 @@ def init_skill(skill_name, path):
         print(f"❌ Error creating SKILL.md: {e}")
         return None
 
-    # Create resource directories with example files
+    # Create the per-skill CHANGELOG.md (canonical structure — REQUIRED for every skill).
+    # Kept OUT of SKILL.md so version history never burns context when the skill is loaded.
+    changelog_path = skill_dir / 'CHANGELOG.md'
     try:
-        # Create scripts/ directory with example script
-        scripts_dir = skill_dir / 'scripts'
-        scripts_dir.mkdir(exist_ok=True)
-        example_script = scripts_dir / 'example.py'
-        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
-        example_script.chmod(0o755)
-        print("✅ Created scripts/example.py")
-
-        # Create references/ directory with example reference doc
-        references_dir = skill_dir / 'references'
-        references_dir.mkdir(exist_ok=True)
-        example_reference = references_dir / 'api_reference.md'
-        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
-        print("✅ Created references/api_reference.md")
-
-        # Create assets/ directory with example asset placeholder
-        assets_dir = skill_dir / 'assets'
-        assets_dir.mkdir(exist_ok=True)
-        example_asset = assets_dir / 'example_asset.txt'
-        example_asset.write_text(EXAMPLE_ASSET)
-        print("✅ Created assets/example_asset.txt")
+        changelog_path.write_text(CHANGELOG_TEMPLATE.format(skill_name=skill_name))
+        print("✅ Created CHANGELOG.md")
     except Exception as e:
-        print(f"❌ Error creating resource directories: {e}")
+        print(f"❌ Error creating CHANGELOG.md: {e}")
         return None
 
+    # Resource directories (scripts/, references/, assets/) are created ON DEMAND — only
+    # when the skill actually needs them. We do NOT scaffold empty placeholder dirs (noise).
+    # See references/skill-structure.md for what each folder is for.
+
     # Print next steps
     print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
     print("\nNext steps:")
-    print("1. Edit SKILL.md to complete the TODO items and update the description")
-    print("2. Customize or delete the example files in scripts/, references/, and assets/")
-    print("3. Run the validator when ready to check the skill structure")
+    print("1. Edit SKILL.md: complete the description (no angle brackets), pick the effort")
+    print("   baseline, and paste the ## Project Context + ## Effort headers from")
+    print("   framework/templates/*.snippet.md.")
+    print("2. Fill CHANGELOG.md's 1.0.0 entry (date + one-line summary).")
+    print("3. Add references/ (loaded on demand), assets/ (output templates), or scripts/")
+    print("   (executables) ONLY if the skill needs them — no empty placeholders.")
+    print("4. Run scripts/quick_validate.py <skill_dir> to check the structure.")
 
     return skill_dir