From bdba841eb3586e55e768c0c3c9ea9aeabd7fb1af Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:01 +0200 Subject: [PATCH 1/8] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20deprecate=20skill-c?= =?UTF-8?q?reator-agnostic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit skill-creator-agnostic is no longer maintained and scheduled for removal in 1.0.0. This skill has been superseded by Anthropic's skill-creator with repository-level governance rules documented in AGENTS.md. Update repo documentation and mark skill as deprecated shim. --- AGENTS.md | 6 +- skills/skill-creator-agnostic/SKILL.md | 202 ++---------------- .../skill-creator-agnostic/evals/evals.json | 95 +++----- 3 files changed, 43 insertions(+), 260 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e3bc94d..25c46b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Repository-level rules for AI agents working in this codebase. ## Local Shell Execution -Agents may use any appropriate local shell. When using PowerShell syntax or executing a `.ps1` script locally, use PowerShell 7+ through `pwsh`; never invoke `powershell` or `powershell.exe`. This does not prescribe GitHub Actions shell choices. +Agents may use any appropriate local shell. When using PowerShell syntax or executing a `.ps1` script locally, use PowerShell 7+ through `pwsh`; never invoke `powershell` or `powershell.exe`. This does not prescribe GitHub Actions shell choices. ## Eval Isolation @@ -54,9 +54,11 @@ Agents must never automatically commit code changes or push to remote repositori Always use the `skill-creator` skill (by Anthropic) when creating new skills, modifying existing skills, or running evals. It enforces best practices for structure, description quality, testing, and progressive disclosure. Do not create or edit skills manually without invoking it first. +`skill-creator-agnostic` is deprecated, no longer maintained, and retained only for backward compatibility until 1.0.0. Agents must not use it for new skill creation, skill modification, or benchmarking; use Anthropic's `skill-creator` directly and apply the repository-specific requirements from this `AGENTS.md`. + ## Third-Party Skills -Never modify skills maintained by others (e.g. `skill-creator` by Anthropic). If a third-party skill needs repo-specific behavior, add the rule here in `AGENTS.md` — not in the skill file itself. Upstream updates will overwrite local edits without warning. +Never modify skills maintained by others (e.g. `skill-creator` by Anthropic). If a third-party skill needs repo-specific behavior, add the rule here in `AGENTS.md` — not in the skill file itself, and not in a companion overlay around the third-party skill. Upstream updates will overwrite local edits without warning. ## Local Install Sync diff --git a/skills/skill-creator-agnostic/SKILL.md b/skills/skill-creator-agnostic/SKILL.md index df21822..e8ac43a 100644 --- a/skills/skill-creator-agnostic/SKILL.md +++ b/skills/skill-creator-agnostic/SKILL.md @@ -1,198 +1,26 @@ --- name: skill-creator-agnostic description: > - Adds runner-agnostic guardrails on top of Anthropic's skill-creator for creating, modifying, and benchmarking skills across Codex, GitHub Copilot, Opus, and similar agents. Use whenever skill work must follow temp-workspace isolation, valid `iteration-N/eval-name/{config}/run-N/` benchmark layout, honest measured-vs-simulated labeling, UTF-8-safe artifact generation, and repo-managed skill sync/README update rules. Treat requests like "turn this workflow into a skill", "benchmark this skill", "compare with_skill and without_skill", "why is aggregate_benchmark.py showing zeros", or "make this skill robust across agents" as automatic triggers. + DEPRECATED — no longer maintained and scheduled for removal in 1.0.0. Retained only for backward compatibility. Do not use for new skill creation, modification, or benchmarking. Use Anthropic's `skill-creator` directly and apply this repository's skill-authoring rules from `AGENTS.md` instead. --- # Skill Creator Agnostic -This skill is a thin overlay on Anthropic's `skill-creator`. It does not replace the upstream workflow; it adds cross-runner and repo-level guardrails so skill work stays reliable across Codex, Copilot, Opus, and similar agents. +> [!CAUTION] +> **Deprecated / obsolete.** +> **No longer maintained.** +> **Scheduled for removal in 1.0.0.** +> **Do not use for new skill work.** +> Use Anthropic `skill-creator` + `AGENTS.md` instead. -Before benchmarking, read `references/benchmark-contract.md`. +This skill is now only a deprecation shim. It exists so older installs and direct invocations get redirected to the supported workflow instead of continuing to expose an obsolete companion implementation. -On Windows or when running from PowerShell, also read `references/windows-powershell-benchmarking.md`. +## Redirect behavior -## Critical +If this skill is invoked, it should do only the following: -- Start from Anthropic's `skill-creator` workflow. Use this skill to add environment and repo guardrails, not to fork or replace the upstream skill. -- Do not edit third-party skills such as Anthropic's `skill-creator` to encode repo-specific behavior. Keep those rules in repo-managed files and companion skills instead. -- Do not assume any specific runner CLI exists. Choose the benchmark runner from what is actually available in the current environment. -- When the chosen runner supports sub-agents, background agents, or equivalent parallel executions, use that capability for `MEASURED` benchmarks by default instead of running evals serially. -- Keep all eval workspaces under a temp root such as `$env:TEMP/-workspace/`, never inside the source repo. -- For repo-managed skills, keep `skills//`, `~/.claude/skills//`, and `~/.agents/skills//` in sync before calling the work done. -- Every repo-managed skill must keep a per-skill `evals/evals.json`. -- If an eval entry declares `files`, treat those paths as skill-relative fixtures and stage them into the temp workspace for both benchmark configurations. -- Benchmark directories must follow `iteration-N/eval-name/{config}/run-N/` exactly, and the eval directory itself must start with `eval-`; do not flatten files directly under `with_skill/` or `without_skill/`. -- `grading.json` must include both `expectations` and a populated `summary` object with `passed`, `failed`, `total`, and `pass_rate`. -- Generate `benchmark.json` through `skill-creator/scripts/aggregate_benchmark.py`; never hand-author it. -- Generate the human review artifact through `skill-creator/eval-viewer/generate_review.py`; do not build custom HTML when the upstream viewer already fits. -- Write JSON as UTF-8 without BOM so Python tooling can load it reliably. -- Distinguish benchmark modes explicitly: `MEASURED` for real model executions, `SIMULATED` for hand-authored or scripted expected outputs. Never present simulated outputs as measured. -- A `MEASURED` benchmark may still show zero delta or parity between configurations. That is a valid measured result, not a reason to relabel the run as simulated. - -## Workflow - -### Step 1: Classify the skill task - -Decide which of these modes the user is asking for: - -- new skill creation -- existing skill modification -- skill benchmark repair/debugging -- benchmark interpretation or review - -Load Anthropic's `skill-creator` for the base workflow, then apply this overlay for cross-runner and repo-specific execution discipline. - -### Step 2: Inspect the local environment before choosing the runner - -Choose the benchmark execution path from actual available capabilities, not from memory or assumptions. - -- Check whether a callable agent runner is available. -- If one exists, prefer a real `MEASURED` benchmark. -- If that runner can execute sub-agents or equivalent background tasks, prefer parallel paired runs over serial execution. -- If no callable runner exists, you may still validate the pipeline with a `SIMULATED` benchmark, but label it clearly as such. -- Explain the chosen mode up front whenever the distinction matters to the user. -- If the callable runner is Codex CLI on Windows, verify the exact invocation shape with a tiny smoke run before spawning the full benchmark harness. - -Do not frame the workflow around one vendor-specific CLI unless that CLI is actually present. - -### Step 3: Set up the benchmark workspace - -Create the workspace under temp and keep it isolated from the real repo. - -- Use a short path such as `$env:TEMP/-workspace/`. -- Put fixture repos, test branches, transcripts, and benchmark outputs there. -- Never commit workspace artifacts back into the source repository unless the user explicitly asked for checked-in examples or harnesses. - -### Step 4: Build the eval contract before running anything - -Read or create the per-skill `evals/evals.json`, then ensure each eval has a corresponding workspace shape: - -```text -iteration-N/ - eval-1-name/ - eval_metadata.json - fixtures/ - with_skill/ - run-1/ - grading.json - timing.json - outputs/ - without_skill/ - run-1/ - grading.json - timing.json - outputs/ -``` - -Keep `eval_metadata.json` at the eval-directory level. Put run artifacts under `run-N/` so `aggregate_benchmark.py` can discover them. -If `evals/evals.json` declares `files`, copy those skill-relative fixtures into `fixtures/` at the eval-directory level and make them available to both runs. -Do not invent custom eval directory names such as `dependency-upgrades-vs-build-refactor/` without the `eval-` prefix. Anthropic's aggregation tooling discovers `eval-*` directories, not arbitrary names. - -### Step 5: Run paired benchmarks - -Run each eval in paired configurations: - -- `with_skill`: the skill under test is active -- `without_skill`: baseline with no skill for new skills, or a previous/ original version for existing skills - -For `MEASURED` runs: - -- if the runner supports sub-agents, spawn the paired executor runs for all evals in parallel in the same turn when practical -- save the real outputs -- save transcripts or command logs when available -- keep timings and token counts tied to the actual run -- use the same staged fixture files for both `with_skill` and `without_skill` runs when the eval declares `files` -- if the runner accepts prompts positionally, pass the prompt as a single argument or via stdin instead of relying on shell-quoted fragments that can be reparsed as CLI flags or extra arguments -- if the runner offers JSONL or event-stream output, keep that raw event file in `outputs/`; it is the fallback source of truth when a convenience output file such as `last-message.txt` is missing -- once executor runs finish, grade them in parallel too when the runner supports that pattern and the grading work is independent - -For `SIMULATED` runs: - -- write clearly labeled expected outputs -- use them only to validate layout, grading, aggregation, and viewer integration -- never claim the result measures model quality - -### Step 6: Grade each run deterministically when possible - -Prefer scripts or direct file/diff checks over impressionistic grading. - -Each `grading.json` must minimally look like this: - -```json -{ - "expectations": [ - { - "text": "Uses iteration-N/eval-name/{config}/run-N/ layout", - "passed": true, - "evidence": "Found run-1/grading.json and run-1/timing.json" - } - ], - "summary": { - "passed": 1, - "failed": 0, - "total": 1, - "pass_rate": 1.0 - } -} -``` - -If `summary` is missing or empty, the aggregation output is not trustworthy. - -### Step 7: Aggregate and generate the review artifacts - -After the paired runs are graded: - -1. Resolve the installed Anthropic `skill-creator` root first, usually under `~/.agents/skills/skill-creator/` or `~/.claude/skills/skill-creator/`. -2. Run `scripts/aggregate_benchmark.py` from that resolved `skill-creator` root. -3. Verify that the generated `benchmark.json` contains discovered runs and a non-empty `run_summary`. -4. Run `eval-viewer/generate_review.py` from that same resolved `skill-creator` root to create the human review artifact. - -If the viewer shows outputs but the benchmark metrics are zero, suspect run layout or `grading.json.summary` before blaming the viewer. - -### Step 8: Interpret results honestly - -Summarize benchmark outcomes with plain language: - -- pass-rate delta -- time and token tradeoffs -- whether the benchmark is `MEASURED` or `SIMULATED` -- which assertions are discriminating versus weak/non-discriminating - -Call out benchmark limitations directly. For example: - -- fixture gaps that leave an assertion only partially tested -- synthetic outputs used for pipeline validation -- missing transcripts or token counts in a measured run -- parity results where both configurations pass, meaning the eval validates the artifact pipeline but does not yet discriminate skill value - -### Step 9: Finish repo-managed skill work cleanly - -For repo-managed skills: - -- sync changed skill files across the repo copy, `~/.claude`, and `~/.agents` -- update `README.md` -- run `scripts/validate-skill-templates.ps1` -- keep benchmark artifacts in temp unless the user explicitly wants them checked in - -## Good Output Characteristics - -- Treats Anthropic's `skill-creator` as the base workflow and this skill as the overlay. -- Talks about available runner capability instead of assuming one product-specific CLI. -- Uses parallel paired executor and grader runs by default when the available runner supports sub-agents or equivalent background tasks. -- Resolves the installed `skill-creator` path before calling benchmark scripts or the review viewer. -- Produces valid benchmark artifacts that `aggregate_benchmark.py` and `generate_review.py` consume without repair work. -- Labels synthetic benchmarks as `SIMULATED` and live executions as `MEASURED`. -- Treats measured parity as an honest outcome instead of overclaiming improvement. -- Explains why a benchmark failed in terms of layout, grading schema, encoding, or environment reality instead of hand-waving. - -## Bad Output Characteristics - -- Presenting hand-authored outputs as if they were independent model runs. -- Hand-writing `benchmark.json` instead of generating it. -- Flattening files directly under `with_skill/` or `without_skill/`. -- Naming eval directories without the `eval-*` prefix and then blaming the aggregator for finding zero runs. -- Saying "use the Claude CLI" or any other vendor tool when the environment has not shown that capability. -- Running a `MEASURED` benchmark serially by habit even though the available runner supports safe parallel paired runs. -- Relabeling a real but parity-only run as `SIMULATED` just because the delta is zero. -- Treating a viewer with qualitative outputs as proof that the numeric benchmark is valid. +1. State that `skill-creator-agnostic` is deprecated, obsolete, and no longer maintained. +2. State that it remains only for backward compatibility and will be removed in **1.0.0**. +3. Redirect new skill creation, modification, and benchmarking work to Anthropic's `skill-creator`. +4. Apply the repository-specific skill-authoring, evaluation, sync, and validation rules from `AGENTS.md`. +5. Do not continue or recommend the historical `skill-creator-agnostic` workflow as an alternative implementation. diff --git a/skills/skill-creator-agnostic/evals/evals.json b/skills/skill-creator-agnostic/evals/evals.json index 680a1a9..277240f 100644 --- a/skills/skill-creator-agnostic/evals/evals.json +++ b/skills/skill-creator-agnostic/evals/evals.json @@ -3,93 +3,46 @@ "evals": [ { "id": 1, - "prompt": "We are adding a new repo-managed skill. Give me the benchmark plan and artifact contract so I can compare with_skill and without_skill from a temp workspace.", - "expected_output": "The response keeps the benchmark in temp, preserves Anthropic skill-creator as the base workflow, and requires aggregate_benchmark.py plus generate_review.py artifacts.", + "prompt": "We are adding a new repo-managed skill to this repository. Which skill-authoring workflow should I use?", + "expected_output": "The response redirects new skill work to Anthropic skill-creator plus the repository rules in AGENTS.md and does not recommend skill-creator-agnostic for new work.", "expectations": [ - "Treats Anthropic skill-creator as the base workflow rather than replacing it", - "Requires a temp workspace outside the source repo", - "Uses paired with_skill and without_skill configurations", - "Requires benchmark.json to be generated by aggregate_benchmark.py", - "Requires the review artifact to come from generate_review.py" + "Identifies skill-creator-agnostic as deprecated or obsolete", + "Redirects new skill creation work to Anthropic skill-creator", + "Tells the reader to apply the repository-specific rules from AGENTS.md", + "Does not recommend skill-creator-agnostic as a companion or alternative implementation" ] }, { "id": 2, - "prompt": "aggregate_benchmark.py keeps showing zero runs even though review.html has outputs. Diagnose the likely benchmark mistake.", - "expected_output": "The response identifies the run-N workspace layout and grading summary contract as the first things to inspect.", + "prompt": "Use the skill-creator-agnostic skill to help me update an existing repo-managed skill.", + "expected_output": "The response says the skill itself is deprecated and no longer maintained, and redirects the work to Anthropic skill-creator plus AGENTS.md.", "expectations": [ - "Identifies eval-N//run-N/ as the required layout instead of flattening files under the config directory", - "Identifies grading.json summary as required for meaningful aggregation", - "Distinguishes a viewer showing outputs from a valid numeric benchmark", - "Avoids blaming the viewer before checking workspace layout and grading data" + "Direct invocation is handled as a deprecation redirect rather than an operational workflow", + "States that skill-creator-agnostic is no longer maintained", + "Redirects modification work to Anthropic skill-creator", + "Points to AGENTS.md for repository-specific requirements" ] }, { "id": 3, - "prompt": "We are on Windows PowerShell and Python keeps rejecting the JSON benchmark files. Tell me the likely artifact problem and how to prevent it.", - "expected_output": "The response points to UTF-8 without BOM and other PowerShell-specific benchmark hygiene issues.", + "prompt": "Will skill-creator-agnostic stay around, or is it being removed?", + "expected_output": "The response communicates that the skill is deprecated, retained only for backward compatibility, and scheduled for removal in 1.0.0.", "expectations": [ - "Calls out UTF-8 without BOM as the safe JSON encoding", - "Avoids relying on Set-Content or shell defaults without qualification", - "Mentions at least one other PowerShell-specific benchmark pitfall such as provider path resolution or stable .Count handling", - "Keeps the advice grounded in benchmark artifact generation rather than general shell trivia" + "Communicates removal in 1.0.0", + "States that the skill remains only for backward compatibility", + "Describes the skill as deprecated or obsolete", + "Does not describe the skill as removed already" ] }, { "id": 4, - "prompt": "There is no dedicated Anthropic CLI in this environment. Keep the skill benchmark runner-agnostic and tell me what counts as measured versus simulated.", - "expected_output": "The response does not require a vendor-specific CLI, prefers measured runs when a callable runner exists, and labels simulated runs honestly.", + "prompt": "I already have Anthropic skill-creator installed. Should I still keep using skill-creator-agnostic as a benchmark overlay or fallback?", + "expected_output": "The response says no, does not recommend the obsolete workflow, and directs the user to Anthropic skill-creator plus AGENTS.md instead.", "expectations": [ - "Does not require a specific vendor CLI as a precondition", - "Chooses the runner from actual available environment capability", - "Prefers measured runs when a callable runner exists", - "Allows simulated runs only when labeled honestly", - "Never presents simulated outputs as measured" - ] - }, - { - "id": 5, - "prompt": "The benchmark runner supports sub-agents and background jobs. Should the measured skill benchmark still run evals one-by-one, or should it fan out? Tell me the expected execution pattern.", - "expected_output": "The response prefers parallel paired executor runs and parallel grading when the runner supports sub-agents, while keeping the existing benchmark artifact contract intact.", - "expectations": [ - "Prefers parallel paired executor runs over serial execution when the runner supports sub-agents or equivalent background jobs", - "Keeps the benchmark grounded in with_skill and without_skill paired runs rather than a single-sided benchmark", - "Prefers parallel grading for independent runs when the runner supports that pattern", - "Preserves the existing eval- and run-N benchmark artifact contract instead of replacing it with a custom layout" - ] - }, - { - "id": 6, - "prompt": "We already have Anthropic skill-creator. Should we replace it, edit it, or layer our own repo rules on top?", - "expected_output": "The response recommends layering repo-managed guardrails on top of Anthropic skill-creator rather than forking or editing the third-party skill.", - "expectations": [ - "Recommends a thin overlay instead of replacing Anthropic skill-creator", - "Avoids editing third-party skill files for repo-specific behavior", - "Keeps repo-managed sync and README update expectations in scope for first-party skills", - "Frames the new skill as cross-runner guidance rather than a single-runner fork" - ] - }, - { - "id": 7, - "prompt": "This skill's evals.json includes files like evals/files/input.md. How should the benchmark runner handle them so with_skill and without_skill stay comparable?", - "expected_output": "The response treats files as skill-relative fixtures, stages them into the temp workspace, and uses the same inputs for both configurations.", - "expectations": [ - "Treats eval files as skill-relative fixture paths rather than workspace-relative paths", - "Stages declared fixture files into the temp eval workspace before running either configuration", - "Uses the same staged fixtures for with_skill and without_skill runs", - "Keeps the guidance grounded in the existing iteration-N/eval-name/{config}/run-N/ benchmark contract" - ] - }, - { - "id": 8, - "prompt": "We have Codex CLI on Windows PowerShell, and my measured benchmark keeps derailing: one run says unexpected argument, another run misses last-message.txt, and aggregate_benchmark.py ignores my custom folder name. What should the runner-agnostic workflow tell me to do?", - "expected_output": "The response keeps the run measured when a real runner exists, calls out safe prompt passing for Codex CLI, requires eval-* directory names, and uses raw event output as the fallback source when convenience files are missing.", - "expectations": [ - "Keeps Codex CLI framed as a valid callable runner rather than forcing a different vendor CLI", - "Advises passing prompts safely as one explicit argument or via stdin instead of brittle shell quoting", - "Requires eval directories to keep the eval-* prefix so Anthropic aggregation tooling can discover them", - "Uses JSONL or event output as the fallback source when last-message or similar convenience files are missing", - "Explains that a real parity run remains MEASURED even when the pass-rate delta is zero" + "Rejects skill-creator-agnostic as the supported path for new benchmarking work", + "Redirects to Anthropic skill-creator", + "Points to AGENTS.md for repository-specific rules", + "Does not present the obsolete workflow as a fallback or parallel implementation" ] } ] From a116390f6b21d86ed460b1484da1bf9caa51c42c Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:23 +0200 Subject: [PATCH 2/8] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20improve=20git-keep-a-c?= =?UTF-8?q?hangelog=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refactor skill instructions and update eval definitions to enhance clarity and maintainability of the changelog generation workflow. --- skills/git-keep-a-changelog/SKILL.md | 92 ++++++++++++++++---- skills/git-keep-a-changelog/evals/evals.json | 36 ++++++++ 2 files changed, 110 insertions(+), 18 deletions(-) diff --git a/skills/git-keep-a-changelog/SKILL.md b/skills/git-keep-a-changelog/SKILL.md index 3617ee3..2a089c7 100644 --- a/skills/git-keep-a-changelog/SKILL.md +++ b/skills/git-keep-a-changelog/SKILL.md @@ -1,7 +1,7 @@ --- name: git-keep-a-changelog description: > - Create or update CHANGELOG.md from git history using Keep a Changelog 1.1.0 style. Use when the user asks to create/update changelog, draft release notes, or mentions SemVer-aware summaries. Trigger phrases: "finalize", "ready to release", "rtr", "release" (especially with version branches like v0.3.1/...), "yolo", "auto". Reads full commit bodies and diffs, treats the selected branch or range as author-agnostic scope by default, creates compliant structure with required SemVer highlights, infers versions from branches, must ask a mandatory Yes / No / Custom confirmation question before including pending staged, unstaged, or untracked worktree changes in a concrete release draft (bypassed in yolo/auto mode — all changes included automatically), edits directly for review, preserves prose wrapping, avoids commit-log dumps. + Create or update CHANGELOG.md from git history using Keep a Changelog 1.1.0 style. Use when the user asks to create/update changelog, draft release notes, or mentions SemVer-aware summaries. Trigger phrases: "finalize", "ready to release", "rtr", "release" (especially with version branches like v0.3.1/...), "yolo", "auto". Reads full commit bodies and diffs, treats the selected branch or range as author-agnostic scope by default, creates compliant structure with required SemVer highlights, infers versions from branches, must ask a mandatory Yes / No / Custom confirmation question before including pending staged, unstaged, or untracked worktree changes in a concrete release draft (bypassed in yolo/auto mode — all changes included automatically), edits directly for review, preserves prose wrapping, avoids commit-log dumps, and classifies only surviving base-to-HEAD release outcomes. compatibility: > Requires Git and PowerShell 7+ for deterministic branch-scope resolution. --- @@ -59,6 +59,45 @@ These checkpoints cannot be skipped or bypassed, even when the user's opening re 3. Release highlight contract: every concrete release entry must include a release highlight paragraph that explicitly classifies the release as `major`, `minor`, or `patch`. 4. Bullet punctuation: all bullets must end with `,` except the final bullet in each populated section, which must end with `.` Do not finish the edit until this is consistent. +## Deterministic Reduction Model + +When the comparison scope is resolved, use this model: + +```text +Result = semantic_delta(Base, HEAD [+ approved pending changes]) +History = provenance used to explain Result +``` + +History is evidence; the resulting state is truth. + +Reduce first. Interpret second. Summarize last. + +1. Inspect cumulative manifest and version deltas across `diff_range`. +2. Inspect the cumulative base-to-`HEAD` diff. +3. Inspect any approved pending worktree changes that are part of the draft. +4. Determine which changes actually survive at the final state. +5. Read chronological commit subjects and bodies as supporting context. +6. Use history to explain the surviving outcomes, then map them into Keep a Changelog sections. + +Do not summarize commits one by one and deduplicate the prose afterward. Classify only surviving release outcomes. + +Reconciliation rules: + +- Base absent and `HEAD` absent -> omit it. +- Base absent and `HEAD` present -> one surviving `Added` outcome in its final form. +- Base present and `HEAD` absent -> one surviving `Removed` outcome. +- Base present and identical `HEAD` state -> omit it. +- Base present and changed `HEAD` state -> one surviving modification whose section is derived from the final delta. +- Equivalent entity at path A in base and path B in `HEAD` -> treat it as a rename or move when the cumulative diff supports that, not `Added` plus `Removed`. + +Examples: + +- Dependency `1.0 -> 2.0 -> 1.0` -> no changelog entry. +- Feature added, fixed three times, then removed -> no changelog entry. +- Existing behavior changed and then reverted exactly -> no changelog entry. +- File deleted and recreated identically -> no changelog entry. +- One capability added, revised, and still present -> usually one `Added` bullet describing its final form, not separate `Added`, `Changed`, and `Fixed` bullets. + ## Release Highlight Contract Every updated changelog entry must begin with a short human-written highlight paragraph directly below the heading. @@ -207,7 +246,7 @@ For branch-derived scope, inspect the resolver output before reading history or If any check fails, stop without editing `CHANGELOG.md`. Report the resolved refs and ask for the correct base branch. This is a correctness failure, not a reason to guess another range. -### Step 4: Read the full history and net effect +### Step 4: Read the cumulative result before the chronology Follow these sub-steps in order. Manifest detection and cumulative manifest diffs must run before commit-body interpretation. @@ -229,25 +268,17 @@ git diff -- package.json Parse the cumulative delta: which packages were added, removed, upgraded, or downgraded, and the exact before → after versions that survive at `HEAD`. This is the authoritative dependency evidence. Individual commit messages may describe partial steps; they do not override the resulting manifest diff. -**4c — Read the full branch-unique commit log.** Use the emitted `history_range`: - -```bash -git log --reverse --format=medium -git log --reverse --stat --format=medium -``` - -Read every selected contributor's full subject and body. The boundary commit and any commit already reachable from the comparison branch are absent by construction and must remain absent. - -**4d — Inspect the net diff for non-manifest changes.** Use the emitted `diff_range`: +**4c — Inspect the cumulative diff before history.** Use the emitted `diff_range`: ```bash +git diff --name-status -M -C git diff --stat git diff ``` -Verify that fixups and partial reversals do not distort the changelog. Prefer the final user-visible or maintainer-meaningful outcome over the implementation path. +Resolve the cumulative file, config, dependency, and behavior deltas from base to `HEAD`. Do not derive the changelog by accumulating labels from individual commits. -**4e — Include approved pending changes.** When the user approved pending changes in Step 3, also inspect the selected worktree deltas. In yolo/auto mode, inspect all of them automatically: +**4d — Inspect approved pending changes when they are in scope.** When the user approved pending changes in Step 3, also inspect the selected worktree deltas. In yolo/auto mode, inspect all of them automatically: ```bash git diff --cached @@ -255,26 +286,47 @@ git diff git ls-files --others --exclude-standard ``` -Pending changes are additive to the already-isolated committed scope. They never justify widening `history_range` or `diff_range`. +Pending changes are additive final-state evidence. They never justify widening `history_range` or `diff_range`. + +**4e — Determine the surviving outcomes at the final state.** + +- Eliminate exact reversions, temporary files/features, and dependency churn that returned to the base value. +- Merge intermediate add/change/fix churn into the final surviving capability or behavior. +- Preserve rename/move as one surviving outcome when the cumulative diff supports it. +- Do not place one surviving outcome under multiple changelog sections merely because its lifecycle crossed several verbs during development. + +**4f — Read the full branch-unique commit log.** Use the emitted `history_range`: + +```bash +git log --reverse --format=medium +git log --reverse --stat --format=medium +``` + +Read every selected contributor's full subject and body. The boundary commit and any commit already reachable from the comparison branch are absent by construction and must remain absent. + +Use history only to explain the surviving outcomes, confirm rename intent, extract accurate user-facing terminology, and understand why a fix matters. Never let an intermediate commit override contradictory final-state evidence. ### Step 5: Classify the release -Infer the SemVer class from the actual change set. +Infer the SemVer class from the surviving change set. - `major` when the release includes breaking removals, required migration, incompatible contract changes, or other true breaking behavior. - `minor` when the release adds meaningful new capabilities without breaking existing consumers. - `patch` when the release is primarily fixes, service updates, docs, validation, maintenance, dependency work, or other non-breaking refinement. -Do not over-classify from dramatic wording in a commit subject. The net effect matters more than the phrasing of one commit. +Do not over-classify from dramatic wording in a commit subject. The surviving delta matters more than the phrasing of one commit. ### Step 6: Curate the changelog content Write the release highlight first, then the populated sections. -- Map the net effect into `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`. +- Map only the surviving outcomes into `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`. - Keep bullets curated and human-written. - Merge overlapping commits into one bullet when they describe the same real outcome. +- A capability that was added, fixed, and refined but survives usually appears once in the section that best describes its final state. +- A capability, file, or dependency change that returned to the base state stays out of the changelog entirely. - Drop low-signal churn such as typo-only commits, trivial fixups, or mechanical follow-ups unless they materially change the release story. +- Use history only for naming, rationale, rename intent, and bug context. Do not let a dramatic commit message manufacture an extra bullet that the final diff does not support. - Use natural prose line breaks. Keep paragraphs and bullets readable, but do not column-wrap them artificially or target a fixed line width. - End each bullet with `,` except the final bullet in a populated section, which must end with `.`. @@ -302,6 +354,7 @@ After updating `CHANGELOG.md`, stop and let the user review the file. Do not com - Includes a required SemVer-aware release highlight. - Creates a compliant `CHANGELOG.md` scaffold when the file is missing. - Reflects the meaning of full commit bodies and the net diff. +- Classifies only surviving base-to-`HEAD` outcomes; reverted or cancelled work disappears. - Resolves branch-derived scope with the bundled script, uses branch-unique commits for history and the merge boundary for net diffs, and verifies that no selected commit is already reachable from the comparison branch. - Excludes the comparison boundary from both concrete releases and `[Unreleased]`; changelog heading choice never changes Git range inclusivity. - Treats the selected branch or range as author-agnostic scope and includes every contributor's commits unless the user explicitly narrows by author. @@ -316,6 +369,8 @@ After updating `CHANGELOG.md`, stop and let the user review the file. Do not com - **CRITICAL — Including the comparison boundary or previous release commit in a new release.** This silently duplicates already-released work. Never widen a branch-derived range with `^`; require the resolver's bleed guard to pass before writing. - Copying commit subjects line by line into the changelog. +- Reporting temporary features, files, APIs, or dependencies that leave no surviving base-to-`HEAD` change. +- Putting one surviving capability under multiple sections because its intermediate commits used different verbs. - Omitting the release highlight. - Failing to classify the release as major, minor, or patch. - Refusing to proceed just because `CHANGELOG.md` does not exist yet. @@ -328,5 +383,6 @@ After updating `CHANGELOG.md`, stop and let the user review the file. Do not com - Filtering the selected branch or range to the current user's or current contributor's commits, or treating "my changes" as the default release scope. - Using the feature branch's same-name remote tracking ref as the comparison base, producing an empty or misleading branch scope. - Letting a concrete version heading or yolo/auto mode change committed-history inclusivity. +- Summarizing commit chronology first and trying to deduplicate the prose afterward instead of reducing the final state first. - Understating dependency or version changes because the skill only read individual commit diffs and never inspected the surviving manifest delta from base to `HEAD`. - Reading commit messages before running manifest diffs, then reporting only the packages mentioned in whichever commits happened to be read first, rather than the full cumulative set from the manifest diff. diff --git a/skills/git-keep-a-changelog/evals/evals.json b/skills/git-keep-a-changelog/evals/evals.json index 6c7a20a..bf76651 100644 --- a/skills/git-keep-a-changelog/evals/evals.json +++ b/skills/git-keep-a-changelog/evals/evals.json @@ -178,6 +178,42 @@ "Uses the same deterministic bleed guard as non-yolo branch-derived releases", "Does not contact or switch to main to invent a broader release narrative" ] + }, + { + "id": 16, + "prompt": "Create a deterministic temp git repo outside the current repository under `$env:TEMP`, then use git-keep-a-changelog there. Start from a base commit containing `CHANGELOG.md`, `src/Widget.cs`, and `Directory.Packages.props`. On branch `v1.2.3/net-result-changelog`, make these commits in order: add `src/Foo.cs`; revise `src/Foo.cs`; delete `src/Foo.cs`; add `src/Bar.cs`; revise `src/Bar.cs` twice; upgrade `Example.Dependency` from `1.0.0` to `2.0.0`; change it back to `1.0.0`. Update `CHANGELOG.md` for the branch and stop after the edit.", + "expected_output": "The changelog entry omits `Foo` and the reverted dependency churn, and contains one surviving added outcome for `Bar` in its final form.", + "expectations": [ + "Omits `Foo` because it leaves no surviving base-to-HEAD change", + "Omits the reverted `Example.Dependency` version churn because the final version matches the base state", + "Describes `Bar` once in its final added form instead of separate Added, Changed, and Fixed bullets", + "Grounds the section content in the cumulative base-to-HEAD result rather than the chronological accumulation of commits", + "Updates `CHANGELOG.md` directly in the temp repo and stops after the edit" + ] + }, + { + "id": 17, + "prompt": "Create a deterministic temp git repo outside the current repository under `$env:TEMP`, then use git-keep-a-changelog there. Start from a base commit containing `CHANGELOG.md`, `src/Service.cs`, `src/Legacy.cs`, and a public API `WidgetClient.Send()`. On branch `v2.0.0/reconcile-api`, make these commits in order: modify `src/Service.cs`; revert that modification exactly; delete `src/Legacy.cs`; restore `src/Legacy.cs` identically; remove `WidgetClient.Send()`; restore `WidgetClient.Send()` unchanged; move `src/Service.cs` to `src/Core/Service.cs` and change its surviving behavior. Update `CHANGELOG.md` and stop after the edit.", + "expected_output": "The changelog omits the exact revert, the identically restored file, and the restored API removal, while describing the surviving moved-and-changed service outcome once.", + "expectations": [ + "Omits the reverted `Service` modification because it no longer survives at `HEAD`", + "Omits the delete-and-identically-restore `Legacy` file because it matches the base state again", + "Does not claim a breaking API removal for `WidgetClient.Send()` because it was restored unchanged", + "Avoids naive duplicate Added plus Removed language for the moved `Service` entity and instead describes the surviving modification once", + "Keeps the changelog grounded in the surviving final delta" + ] + }, + { + "id": 18, + "prompt": "Create a deterministic temp git repo outside the current repository under `$env:TEMP`, then use git-keep-a-changelog there. Start from a base commit with `CHANGELOG.md`, `src/Client.cs`, and `Directory.Packages.props`. On branch `v3.1.0/noisy-release`, make these commits in order: add `SendAsync`; fix it twice; replace its first implementation with a second; add a temporary `LegacyMode` feature and later remove it; upgrade `Newtonsoft.Json` from `13.0.3` to `14.0.0` and later to `14.0.2`; finish with a commit message that claims a security change the final diff does not support. Update `CHANGELOG.md` and stop after the edit.", + "expected_output": "The changelog describes `SendAsync` once in its final form, records one surviving `Newtonsoft.Json` upgrade to `14.0.2`, omits `LegacyMode`, and does not invent the contradicted security entry.", + "expectations": [ + "Describes the surviving `SendAsync` capability once in its final form", + "Records one surviving dependency upgrade from `13.0.3` to `14.0.2`", + "Omits the temporary `LegacyMode` feature because it does not survive into `HEAD`", + "Does not add a Security or other section entry when the final diff contradicts the commit message claim", + "Produces a small set of high-signal release outcomes independent of commit count" + ] } ] } From 2128d80ba3ef982d82e662e19884d62dbbccfa11 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:29 +0200 Subject: [PATCH 3/8] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20improve=20git-nuget-re?= =?UTF-8?q?lease-notes=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refactor skill instructions and update eval definitions to enhance clarity and maintainability of the per-package release notes workflow. --- skills/git-nuget-release-notes/SKILL.md | 76 +++++++++++++++---- .../git-nuget-release-notes/evals/evals.json | 36 +++++++++ 2 files changed, 98 insertions(+), 14 deletions(-) diff --git a/skills/git-nuget-release-notes/SKILL.md b/skills/git-nuget-release-notes/SKILL.md index 82cc626..a2bc532 100644 --- a/skills/git-nuget-release-notes/SKILL.md +++ b/skills/git-nuget-release-notes/SKILL.md @@ -1,7 +1,7 @@ --- name: git-nuget-release-notes description: > - Create or update per-package NuGet release notes from git history for .NET repositories that store cumulative `.nuget/{ProjectName}/PackageReleaseNotes.txt` files. Use this skill whenever the user asks for NuGet release notes, `PackageReleaseNotes.txt`, per-assembly or per-package release notes, or wants git commits turned into package release notes instead of a repo-wide changelog. Treat requests like "update PackageReleaseNotes.txt", "write NuGet release notes from git", "summarize this release per assembly", or "create missing package release notes under .nuget" as automatic triggers. The skill discovers packable `src/` projects, resolves concrete release version and availability per package, creates missing files when needed, preserves cumulative newest-first history, and avoids raw commit-log dumps or unsupported claims. + Create or update per-package NuGet release notes from git history for .NET repositories that store cumulative `.nuget/{ProjectName}/PackageReleaseNotes.txt` files. Use this skill whenever the user asks for NuGet release notes, `PackageReleaseNotes.txt`, per-assembly or per-package release notes, or wants git commits turned into package release notes instead of a repo-wide changelog. Treat requests like "update PackageReleaseNotes.txt", "write NuGet release notes from git", "summarize this release per assembly", or "create missing package release notes under .nuget" as automatic triggers. The skill discovers packable `src/` projects, resolves concrete release version and availability per package, creates missing files when needed, preserves cumulative newest-first history, reduces each package to its surviving base-to-HEAD delta before using history as context, and avoids raw commit-log dumps or unsupported claims. --- # Git NuGet Release Notes @@ -18,6 +18,9 @@ Read `references/package-release-notes-format.md` before writing any release-not - Discover packable projects under `src/`; ignore `test/`, `tuning/`, `tooling/`, and projects that are explicitly non-packable. - Prefer an existing `.nuget/{ProjectName}/` folder when one already exists for the packable project. If none exists, create `.nuget//PackageReleaseNotes.txt`. - For repo-wide requests, every packable `src/` project should end up represented by a corresponding `PackageReleaseNotes.txt` file. +- Treat the package's base-to-`HEAD` state as truth; chronological history is supporting provenance. +- Inspect cumulative package, API, manifest, version, and metadata deltas before classifying the package history. +- Describe only surviving package outcomes. Do not preserve intermediate upgrades, removals, renames, or bug fixes that do not survive into `HEAD`. - Read full commit subjects and bodies before writing the package notes. - Inspect the net diff too; do not classify a package from commit subjects alone. - Use cumulative newest-first history. @@ -33,6 +36,44 @@ Read `references/package-release-notes-format.md` before writing any release-not - Do not invent unsupported changes, package references, or availability. - Ignore odd historical spacing such as non-breaking spaces in older entries; normalize only the block you are writing unless the user asks for a larger cleanup. +## Deterministic Package Delta Model + +When a scope is resolved, use this model for each target package: + +```text +Result = semantic_delta(PackageBase, PackageHEAD) +History = provenance used to explain Result +``` + +History is evidence; the resulting state is truth. + +Reduce first. Interpret second. Summarize last. + +1. Inspect cumulative manifest, property, version, and metadata deltas that affect the package. +2. Inspect the cumulative base-to-`HEAD` diff for the package and its shared packaging files. +3. Determine which package changes actually survive at `HEAD`. +4. Read chronological commit subjects and bodies as supporting context. +5. Use history to explain the surviving outcomes, then map them into the package-note sections. + +Do not accumulate bullets from individual commits and deduplicate them afterward. + +Reconciliation rules: + +- Base state and `HEAD` state are identical -> no entry. +- Dependency, API, metadata, or TFM value that returns to the base state -> no entry. +- Base absent and `HEAD` present -> one surviving added capability or surface area outcome. +- Base present and `HEAD` absent -> one surviving removal. +- Base present and changed `HEAD` state -> one surviving modification, fix, rename, or move derived from the final delta. +- Equivalent entity/path/name moved or renamed -> one rename/move outcome when the cumulative diff supports it, not add plus remove. + +Examples: + +- `Newtonsoft.Json 13.0.3 -> 14.0.0 -> 13.0.3` -> no `# ALM` bullet. +- `Newtonsoft.Json 13.0.3 -> 14.0.0 -> 14.0.2` -> one surviving upgrade from `13.0.3` to `14.0.2`. +- Public API removed and later restored unchanged -> no `# Breaking Changes` bullet. +- Feature added, fixed several times, then removed -> no package-note entry for that feature. +- One capability added, reworked, and still present -> usually one final `ADDED`, `CHANGED`, or `EXTENDED` bullet describing what shipped. + ## Workflow ### Step 1: Resolve the source range @@ -103,22 +144,25 @@ Examples: Do not guess availability from memory if the project file or evaluated MSBuild properties can answer it. -### Step 5: Inspect the actual package changes +### Step 5: Inspect the cumulative package delta first -For each target package, read enough history and diff to understand the real release story for that package. +For each target package, use this order to understand the real release story. -- Read the full commit bodies for the selected range. -- Inspect the net diff for the package's project folder plus shared packaging/build files that materially affect that package. -- Include shared files such as `Directory.Packages.props`, `Directory.Build.props`, `Directory.Build.targets`, and `.nuget/{ProjectName}/` when they affect the package. -- Prefer the net effect over the implementation path when there are fixups or reversals. +- Build the package-specific path set: the package project, its source folder, any package-specific `.nuget/{ProjectName}/` files, and shared packaging/build files that materially affect it. +- Inspect cumulative manifest, property, version, and metadata deltas first. This includes `Directory.Packages.props`, package references in project files, `TargetFramework` / `TargetFrameworks`, package metadata, and other shared packaging files that affect the package. +- Inspect the cumulative base-to-`HEAD` diff for the package paths. +- Determine which package changes survive at `HEAD`: public APIs, dependency versions, TFMs, package metadata, types/members, renames/moves, removals, and bug fixes that still exist. +- Eliminate exact reversions, temporary features, reverted dependency churn, and restored APIs or metadata that match the base state. +- Read the full commit bodies only after the cumulative delta is clear. Use history to explain the surviving outcomes, confirm rename intent, understand migration context, and choose accurate user-facing terminology. Never let an intermediate commit override contradictory final-state evidence. Helpful commands: ```bash -git log --reverse --format=medium -- -git log --reverse --stat --format=medium -- +git diff --name-status -M -C ..HEAD -- git diff --stat ..HEAD -- git diff ..HEAD -- +git log --reverse --format=medium -- +git log --reverse --stat --format=medium -- ``` ### Step 6: Classify the content into the package-note format @@ -127,14 +171,15 @@ Use the normalized section order from `references/package-release-notes-format.m Classification guidance: -- `# ALM`: dependency upgrades, TFM support added/removed, packaging metadata changes, or other release-engineering/package-management changes. -- `# Breaking Changes`: incompatible renames, removals, moved APIs, changed contracts, or behavior that requires consumer action. -- `# New Features`: additive new APIs, capabilities, packages, or newly exposed options. -- `# Improvements`: non-breaking enhancements such as `CHANGED`, `EXTENDED`, `OPTIMIZED`, `DEPRECATED`, or other refinements. -- `# Bug Fixes`: defects corrected for existing behavior. +- `# ALM`: only surviving dependency upgrades/downgrades, TFM support changes, packaging metadata changes, or other release-engineering/package-management changes. Use the final before -> after versions that remain at `HEAD`. +- `# Breaking Changes`: only incompatible renames, removals, moved APIs, changed contracts, or behavior that still requires consumer action at `HEAD`. +- `# New Features`: only additive APIs, capabilities, packages, or options that are absent at the base state and present at `HEAD`. +- `# Improvements`: surviving non-breaking enhancements such as `CHANGED`, `EXTENDED`, `OPTIMIZED`, `DEPRECATED`, or other refinements to existing behavior. +- `# Bug Fixes`: surviving defect corrections for behavior that remains changed versus the base state. - `# References`: package IDs only, and only when the package is an umbrella/meta package or the existing file already carries a references section the current release should preserve. Prefer a minimal truthful block over an inflated one. ALM-only releases are valid when the real change was only dependency or TFM maintenance. +A restored API or reverted dependency upgrade does not earn a section entry. Use history to help group or explain the surviving outcomes, not to manufacture extra bullets. ### Step 7: Write or update PackageReleaseNotes.txt @@ -168,6 +213,7 @@ After updating the relevant `PackageReleaseNotes.txt` files, stop and let the us - Reads like curated package release notes, not a repo-wide changelog. - Keeps one truthful release block per package/version. +- Classifies each package from its surviving base-to-`HEAD` delta; reverted churn disappears. - Uses concrete package/type/member names and namespaces. - Writes the newest release first while preserving older history. - Keeps ALM details explicit when dependencies or TFMs changed. @@ -180,5 +226,7 @@ After updating the relevant `PackageReleaseNotes.txt` files, stop and let the us - Using `Unreleased` or omitting the concrete version line. - Guessing availability instead of reading project metadata. - Dumping commit subjects line by line into the file. +- Reporting temporary dependency, API, metadata, or TFM changes that do not survive into `HEAD`. +- Emitting `# Breaking Changes`, `# New Features`, or `# Bug Fixes` bullets for work that was later restored or removed before release. - Creating empty headings or filler bullets like "misc updates". - Claiming breaking changes, fixes, or references not supported by git and the project/package metadata. diff --git a/skills/git-nuget-release-notes/evals/evals.json b/skills/git-nuget-release-notes/evals/evals.json index d718d4c..aede57d 100644 --- a/skills/git-nuget-release-notes/evals/evals.json +++ b/skills/git-nuget-release-notes/evals/evals.json @@ -58,6 +58,42 @@ "Does not invent unsupported package references", "Keeps the output grounded in git history plus actual project/package metadata" ] + }, + { + "id": 6, + "prompt": "Create a deterministic temp .NET git repo outside the current repository under `$env:TEMP`, then use git-nuget-release-notes there. Start from a base commit with a packable `src/Acme.Core/Acme.Core.csproj`, `.nuget/Acme.Core/PackageReleaseNotes.txt`, and `Directory.Packages.props`. On branch `v2.1.0/net-result-packages`, add a `FeatureFoo` API and later remove it; add a `FeatureBar` API and revise it twice so it survives; change `Newtonsoft.Json` from `13.0.3` to `14.0.0` and back to `13.0.3`; change `Serilog` from `3.0.0` to `4.0.0` and then to `4.1.0`. Update the package release notes and stop after the edit.", + "expected_output": "The package notes omit `FeatureFoo` and the reverted `Newtonsoft.Json` churn, record one surviving `Serilog` upgrade to `4.1.0`, and describe `FeatureBar` once in its final form.", + "expectations": [ + "Omits `FeatureFoo` because it does not survive into the package's final state", + "Omits the reverted `Newtonsoft.Json` change because the final version matches the base state", + "Records one surviving dependency upgrade from `Serilog 3.0.0` to `4.1.0`", + "Describes `FeatureBar` once in its final surviving form instead of scattering its lifecycle across multiple sections", + "Updates `.nuget/Acme.Core/PackageReleaseNotes.txt` directly and stops after the edit" + ] + }, + { + "id": 7, + "prompt": "Create a deterministic temp .NET git repo outside the current repository under `$env:TEMP`, then use git-nuget-release-notes there. Start from a base commit with a packable `src/Acme.Core/Acme.Core.csproj`, `.nuget/Acme.Core/PackageReleaseNotes.txt`, `src/Acme.Core/WidgetClient.cs`, and `src/Acme.Core/LegacyFormatter.cs`. On branch `v3.0.0/api-reconcile`, remove `WidgetClient.LegacySend()` and later restore it unchanged; move `WidgetClient` into a new namespace/path and modify one surviving method; delete `LegacyFormatter.cs` and recreate it identically; delete `ResponseNormalizer.cs` and recreate it with different behavior. Update the package release notes and stop after the edit.", + "expected_output": "The package notes avoid a false breaking-change claim for the restored API, omit the identically restored file churn, and describe the surviving moved-and-changed API and recreated-differently behavior as coherent final outcomes instead of naive add/remove duplication.", + "expectations": [ + "Does not claim a breaking API removal for `WidgetClient.LegacySend()` because it was restored unchanged", + "Omits the delete-and-identically-restore `LegacyFormatter.cs` churn because it matches the base state again", + "Treats the moved `WidgetClient` surface as one coherent surviving rename/move/change outcome rather than Added plus Removed duplication", + "Treats the differently recreated `ResponseNormalizer` behavior as one surviving modification or replacement outcome instead of naive Added plus Removed prose", + "Keeps the release notes grounded in the package's final delta" + ] + }, + { + "id": 8, + "prompt": "Create a deterministic temp .NET git repo outside the current repository under `$env:TEMP`, then use git-nuget-release-notes there. Start from a base commit with a packable `src/Acme.Core/Acme.Core.csproj`, `.nuget/Acme.Core/PackageReleaseNotes.txt`, and package metadata. On branch `v4.0.0/noisy-alm`, temporarily add `net9.0` and later remove it again, add `net10.0` so it survives, temporarily change package icon metadata and restore it, finally update `RepositoryUrl`, and finish with a commit body that claims another dependency upgrade the final diff does not support. Update the package release notes and stop after the edit.", + "expected_output": "The package notes keep only the surviving TFM and metadata changes, omit the reverted ALM churn, and do not echo the contradicted dependency claim from history.", + "expectations": [ + "Records the surviving `net10.0` availability change while omitting the reverted temporary `net9.0` churn", + "Omits the temporary package icon metadata change because it was restored to the base state", + "Keeps the surviving `RepositoryUrl` metadata update instead of replaying every intermediate packaging edit", + "Does not report a dependency change that appears only in the commit body when the final diff contradicts it", + "Uses history as supporting context only after the final package delta is clear" + ] } ] } From c2a193b11eedd491af4d22df36279976db1d89a4 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:34 +0200 Subject: [PATCH 4/8] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20improve=20git-visual-s?= =?UTF-8?q?quash-summary=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refactor skill instructions and update eval definitions to enhance clarity and maintainability of the squash-summary workflow. --- skills/git-visual-squash-summary/SKILL.md | 87 +++++++++++++++---- .../evals/evals.json | 49 +++++++++-- 2 files changed, 111 insertions(+), 25 deletions(-) diff --git a/skills/git-visual-squash-summary/SKILL.md b/skills/git-visual-squash-summary/SKILL.md index 9e0bcb4..8e2fdd1 100644 --- a/skills/git-visual-squash-summary/SKILL.md +++ b/skills/git-visual-squash-summary/SKILL.md @@ -1,7 +1,7 @@ --- name: git-visual-squash-summary description: > - Turn many commits into a curated grouped squash summary compatible with the opinionated wording style of git-visual-commits. Use when the user asks to squash a branch into a concise summary, write a squash-and-merge summary, summarize this branch, summarize a commit range or PR as grouped lines, clean up noisy commit history, or asks for a curated summary without committing. For normal squash-and-merge requests, default to the full current feature branch from merge-base to HEAD against the base branch instead of a same-named tracking remote, include commits from all authors unless the user explicitly narrows by author, and do not ask for yolo because the skill is read-only. Returns grouped lines only, preserves identifiers, merges overlap, drops noise, and avoids changelog wording. + Turn many commits into a curated grouped squash summary compatible with the opinionated wording style of git-visual-commits. Use when the user asks to squash a branch into a concise summary, write a squash-and-merge summary, summarize this branch, summarize a commit range or PR as grouped lines, clean up noisy commit history, or asks for a curated summary without committing. For normal squash-and-merge requests, default to the full current feature branch from merge-base to HEAD against the base branch instead of a same-named tracking remote, include commits from all authors unless the user explicitly narrows by author, and do not ask for yolo because the skill is read-only. Returns grouped lines only, resolves the cumulative base-to-HEAD diff first so reverted churn disappears, preserves identifiers, merges overlap, drops noise, and avoids changelog wording. --- # Git Visual Squash Summary @@ -14,6 +14,39 @@ This skill is non-mutating: it inspects history and diffs, then returns grouped This skill has one job: produce a ready-to-paste squash-and-merge summary for the full current feature branch unless the user explicitly asked for a narrower range. +This skill answers one question: **What would this branch effectively do if it were squashed into one commit now?** + +## Deterministic Reduction Model + +Use this model for every resolved scope: + +```text +Result = semantic_delta(Base, HEAD) +History = provenance used to explain Result +``` + +History is evidence; the resulting state is truth. + +Reduce first. Interpret second. Summarize last. + +```text +resolve scope + ↓ +compute cumulative delta + ↓ +eliminate reverted / cancelled / superseded work + ↓ +identify surviving semantic outcomes + ↓ +consult history for intent and terminology + ↓ +group related surviving outcomes + ↓ +render grouped summary lines +``` + +Do not classify commit 1, then commit 2, then commit 3 and merge duplicate prose afterward. That approach preserves contradictory intermediate states. + ## Non-Negotiable Rules - Never stage, commit, amend, rebase, or otherwise mutate git state. @@ -21,9 +54,12 @@ This skill has one job: produce a ready-to-paste squash-and-merge summary for th - Keep `references/commit-language.md` byte-for-byte aligned with the `git-visual-commits` copy; the validator and CI both enforce that sync contract. - Preserve technical identifiers exactly where possible. - Group by intent, not chronology. +- Classify only changes that survive between the resolved base and `HEAD`. - Retain only distinct high-signal change groups. - Merge repetition and overlapping commits into their parent group. - Drop low-signal noise such as typo-only, fixup-only, and trivial follow-up commits unless they materially change a retained group. +- Dependencies and version pins matter only when they survive into the final diff. +- Do not retain reverted experiments, temporary dependency upgrades, or removed late-stage implementations. - Prefer strong concrete verbs and concise phrasing. - Favor readable GitHub and terminal output over cleverness. - Start the description after the emoji with a lowercase word unless the first word is a case-sensitive technical identifier. @@ -74,41 +110,50 @@ git merge-base HEAD main git merge-base HEAD master ``` -### Step 2: Inspect the actual changes +### Step 2: Inspect the cumulative branch delta first -Do not summarize from commit subjects alone when the range is noisy or long. Inspect both history and net effect so the final message reflects what actually changed. +Do not summarize from commit subjects alone when the range is noisy or long. Inspect the cumulative base-to-`HEAD` delta first so the final message reflects what actually survives. Helpful read-only commands: ```bash +git diff --name-status -M -C ..HEAD +git diff --stat ..HEAD +git diff ..HEAD git log --reverse --oneline git log --reverse --stat --format=medium git log --reverse --format="%h %an <%ae> %s" -git diff --stat ..HEAD -git diff ..HEAD ``` ### Step 3: Collapse to semantic intent Before drafting the summary, reduce the range into the smallest truthful set of retained groups: -- First ask: "Does this group contain dependency or version changes?" If yes, preserve that work as its own retained group before running any collapsing logic. This is a hard gate. -- Collapse repeated fixups into the group they support. -- Merge overlapping commits into the clearest final intent. -- Prefer the net effect over the path taken to get there for refactors, documentation, and build-system changes only. This rule does not apply to dependencies. -- Drop typo-only, whitespace-only, and other low-signal cleanup unless it materially changes a retained group. -- Treat dependency or version baseline changes as their own semantic intent. This is a hard rule. Do not evaluate whether dependencies were later reverted or adjusted; preserve them as a distinct group in the summary. -- Do not absorb package version updates into a generic build-system, configuration, or refactor line just because they landed in the same commit. -- When the diff mixes shared dependency manifests or version pins with build-system metadata or project-structure refactors, keep those as separate retained groups. +- Start from the cumulative base-to-`HEAD` diff, not from commit labels. +- For every relevant file, dependency, version pin, config value, API, or behavior, decide what survives at `HEAD`. +- Eliminate exact reversions, temporary files/features, dependency churn that returned to the base value, and experiments abandoned before `HEAD`. +- Merge repeated fixes, redesigns, and follow-ups into the one surviving outcome they affected. +- If a feature or capability was absent at base and present at `HEAD`, describe it once in its final form. Intermediate fixes do not create extra lines. +- If a feature was added and later removed, omit it. +- If existing behavior changed and then reverted exactly, omit it. +- If a file or API was deleted and restored identically, omit it. +- If a file or API was deleted and recreated differently, usually describe one surviving modification or replacement, not naive removed-plus-added prose, unless the evidence clearly shows a different entity. +- If a path or entity moved or was renamed, describe it as one rename/move outcome when the cumulative diff supports that, not `Added` plus `Removed`. +- Dependency and version groups are important when they survive. Keep them separate from build-system/config/refactor groups when the final diff still shows a distinct surviving version change. +- A dependency or version that returns to the base value does not deserve a retained line. +- Do not absorb surviving package version updates into a generic build-system, configuration, or refactor line just because they landed in the same commit. +- When the diff mixes shared dependency manifests or version pins with build-system metadata or project-structure refactors, keep those as separate retained groups when both survive in the final diff. - Keep documentation-only work separate in your reasoning, but include it only when it represents a meaningful unique change. - Treat late changelog, version-bump, or release-finalization commits as part of the branch by default, then decide here whether they deserve a retained summary line or should be merged into a stronger parent group. - Highlight distinct meaningful efforts instead of forcing one dominant umbrella theme. +- Use chronological history after this reduction to confirm rename intent, extract accurate terminology, understand bug context, and explain why the surviving outcome matters. Never let an intermediate commit override contradictory final-state evidence. -Collapsing checklist: +Reduction checklist: -- Do not collapse if the group contains dependencies. -- Do not collapse if the group contains version pins. -- Only collapse pure refactors, docs, or config changes with no dependency component. +- Does this exact change survive from base to `HEAD`? +- If several commits touched the same surviving outcome, can one line describe its final form truthfully? +- Are dependency/version changes still distinct in the final diff from build/config/refactor work? +- Does any candidate line rely on a commit message the final diff contradicts? If yes, trust the final diff. Ask yourself: "If I had to explain the real work in 2-5 compact lines, what are the distinct changes that mattered?" @@ -156,7 +201,7 @@ Formatting rules: - 🐛 bug is for fixes to broken behavior - ✅ check mark is for new test coverage - If an emoji doesn't fit the actual change, **swap it before presenting the summary**. Do not let the user catch emoji mistakes. -- If a retained line is primarily dependency or version-alignment work, prefer the dependency emoji from the shared reference such as `⬆️`, `⬇️`, `➕`, `➖`, or `📌` rather than a generic config or refactor emoji. +- If a retained line is primarily dependency or version-alignment work that still survives in the final diff, prefer the dependency emoji from the shared reference such as `⬆️`, `⬇️`, `➕`, `➖`, or `📌` rather than a generic config or refactor emoji. - If a retained line is mainly changelog, community-health, or release-status communication, prefer `💬` from the shared reference rather than a generic docs emoji. - Do not add bullets, numbering, a body, rationale paragraph, or chronology recap. - Do not append weak glue like "with", "plus", or "and" just to force several top-level intents into one line. @@ -170,10 +215,13 @@ Output the finished grouped summary lines and stop. Do not run `git commit`, `gi ## Good Output Characteristics - Reads like a curated grouped summary, not a stitched list of commits. +- Answers "what would this branch do if squashed now?" rather than "what happened along the way?" - Reads like a curated, human-written condensed history. - Uses the same emoji-first language as `git-visual-commits`, with prefixes only on explicit request. - Starts descriptions lowercase after the emoji unless preserving a leading technical identifier requires original casing. - Keeps distinct meaningful efforts on separate lines. +- Describes only surviving base-to-`HEAD` outcomes; temporary churn disappears. +- Describes one surviving outcome once, even if many commits touched it. - Drops noisy fixups and typo-only churn instead of preserving them. - Fits naturally beneath a PR title or in compact GitHub and terminal views. - Includes only claims supported by the inspected diff. @@ -188,14 +236,17 @@ Output the finished grouped summary lines and stop. Do not run `git commit`, `gi - Changelog-like wording or release-note phrasing. - Chronological narration of each commit in order. - Dumping raw commit subjects line by line. +- Preserving reverted dependency or version churn just because it happened in history. - Asking the user to choose among commits that are all on the current feature branch when they asked for a squash summary of that branch. - Presenting commit-selection widgets or multiple-choice prompts for ordinary branch-level squash requests. - Filtering the branch to the current user's or current contributor's commits, or treating "my changes" as the default scope. - Collapsing several unique top-level efforts into one stitched sentence. +- Describing a rename/move or delete-and-recreate outcome as naive `Added` plus `Removed` duplication when one surviving outcome is clearer. - Collapsing dependency updates into the same line as build-system configuration or refactor work when the diff shows separate intents. - Starting normal descriptions with uppercase verbs such as `Add`, `Update`, `Refresh`, or `Preserve`. - Filler such as "misc cleanup", "various improvements", or "updates". - Losing or renaming important technical identifiers unnecessarily. - Inventing refactors, fixes, or docs changes not supported by the diff. +- Counting commits instead of surviving outcomes. - Adding a title, body, bullets, or numbered outline. - Exceeding 72 characters on any output line. diff --git a/skills/git-visual-squash-summary/evals/evals.json b/skills/git-visual-squash-summary/evals/evals.json index 525cb13..5d12c1a 100644 --- a/skills/git-visual-squash-summary/evals/evals.json +++ b/skills/git-visual-squash-summary/evals/evals.json @@ -122,7 +122,7 @@ "prompt": "Summarize this branch for squash merge. One branch commit collapses dependency updates and build-system changes into a single subject, while the diff touches Directory.Packages.props plus Directory.Build.targets.", "expected_output": "A grouped squash summary that keeps dependency upgrades as their own retained line, separate from build-system or refactor work, even when those changes landed in the same commit.", "expectations": [ - "Treats dependency or version baseline changes as a separate semantic intent from build-system metadata or refactoring", + "Treats dependency or version baseline changes as a separate semantic intent from build-system metadata or refactoring when both survive in the final diff", "Does not collapse dependency upgrades into a generic build-system or configuration line", "Uses a dependency-oriented emoji such as ⬆️ when a retained line is primarily dependency upgrade work", "Keeps the build-system or refactor effort on its own retained line when the diff shows a separate intent", @@ -132,13 +132,12 @@ { "id": 12, "prompt": "Summarize this branch for squash merge. The history updates Microsoft.NET.Test.Sdk from 18.6.0 to 18.7.0, later adjusts it back to 18.6.0 while keeping other build refactors, and also touches shared project metadata. Use the normal grouped lines only.", - "expected_output": "A grouped squash summary that preserves dependency/version work as its own semantic group instead of treating the version churn as net-zero and collapsing it into build-system or refactor wording.", + "expected_output": "A grouped squash summary that drops the reverted dependency churn, keeps only the surviving build or metadata outcomes, and never invents a dependency line once the version returns to its base value.", "expectations": [ - "Checks for dependency or version changes before applying net-effect collapsing", - "Does not collapse dependency or version-pin work even when later commits revert or adjust the version", - "Treats dependency and version baseline changes as a hard-rule retained semantic group", - "Keeps pure build-system, config, or refactor work separate from dependency/version work", - "Uses a dependency-oriented emoji such as 📌 or ⬆️ when a retained line is primarily dependency or version-pin work", + "Resolves dependency or version groups from the cumulative base-to-HEAD diff rather than from the chronological story alone", + "Omits the `Microsoft.NET.Test.Sdk` change because the final version returns to `18.6.0`", + "Retains only the surviving build or metadata work that remains after the version churn cancels out", + "Does not invent a dependency line merely because the history contained version churn", "Returns grouped summary lines only" ] }, @@ -176,6 +175,42 @@ "Treats author metadata as context only unless the user explicitly asks for an author-filtered summary", "Returns grouped summary lines only without explaining the author-scope rule" ] + }, + { + "id": 16, + "prompt": "Create a deterministic temp git repo outside the current repository under `$env:TEMP`, then use git-visual-squash-summary there. Start from `main` with `README.md` and `src/Widget.cs`. On a feature branch commit sequence is: add `src/Foo.cs`; edit `src/Foo.cs` twice; delete `src/Foo.cs`; change `README.md`; revert the `README.md` change exactly; add `src/Bar.cs`; revise `src/Bar.cs` twice. Return the grouped squash summary lines only for the feature branch versus `main`.", + "expected_output": "The grouped summary omits `Foo` and the reverted `README.md` churn, and emits one surviving added-capability line for `Bar` in its final form.", + "expectations": [ + "Omits `Foo` entirely because it is absent at both the base and `HEAD` states", + "Omits the `README.md` change because it was reverted exactly", + "Describes `Bar` once as one surviving added outcome in its final form", + "Does not produce separate added, changed, or fixed lines for repeated edits to the same surviving file", + "Returns grouped lines only" + ] + }, + { + "id": 17, + "prompt": "Create a deterministic temp git repo outside the current repository under `$env:TEMP`, then use git-visual-squash-summary there. Start from `main` with `src/Service.cs`, `src/Legacy.cs`, and `Directory.Packages.props`. On a feature branch: rename `src/Service.cs` to `src/Core/Service.cs` and modify it; delete `src/Legacy.cs`; restore `src/Legacy.cs` identically; change `Newtonsoft.Json` from `13.0.3` to `14.0.0` and then to `14.0.2`; include an intermediate commit message that claims another package was upgraded even though the final diff does not show it. Return the grouped summary lines only.", + "expected_output": "The grouped summary keeps one coherent move/update line for `Service`, one surviving dependency line for `Newtonsoft.Json 13.0.3 -> 14.0.2`, omits `Legacy`, and ignores the contradicted extra package claim from history.", + "expectations": [ + "Produces one coherent rename/move/change outcome instead of Added plus Removed duplication for `Service`", + "Omits `Legacy` because it matches the base state after being restored identically", + "Reports one surviving dependency upgrade from `Newtonsoft.Json 13.0.3` to `14.0.2`", + "Does not report the contradicted extra package change from commit history when the final diff disagrees", + "Returns grouped lines only" + ] + }, + { + "id": 18, + "prompt": "Create a deterministic temp git repo outside the current repository under `$env:TEMP`, then use git-visual-squash-summary there. Start from `main` with `src/WidgetClient.cs`. On a feature branch: add `SendAsync`; fix it twice; replace the first implementation with a second; add a temporary `LegacyMode` option and later remove it; briefly delete `WidgetClient.Send()` and restore it unchanged; finish with a docs or release-prep follow-up commit. Return the grouped squash summary lines only.", + "expected_output": "The grouped summary keeps one surviving `SendAsync` capability line, omits `LegacyMode`, omits the restored `Send()` removal, and produces a small number of high-signal lines independent of commit count.", + "expectations": [ + "Keeps one line for the surviving `SendAsync` capability in its final form", + "Omits the temporary `LegacyMode` work because it does not survive into `HEAD`", + "Does not emit a breaking-removal claim for `WidgetClient.Send()` because it was restored unchanged", + "Produces a small number of high-signal lines independent of commit count", + "Does not emit one line per fixup or implementation swap" + ] } ] } From b03708aee892652a61be275da7df744f9e487c3e Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:40 +0200 Subject: [PATCH 5/8] =?UTF-8?q?=F0=9F=94=A8=20add=20skill=20template=20val?= =?UTF-8?q?idation=20script?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add deterministic validator for skill structure, frontmatter, and file organization. Ensures consistent skill repository conventions and compliance with AGENTS.md requirements. --- scripts/validate-skill-templates.ps1 | 61 ++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index e74d1a0..96d021e 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -768,6 +768,28 @@ Add-ValidationResult -Results $results -Name 'Repository docs define the local s Assert-Contains -Name 'CONTRIBUTING.md' -Content $contributing -Needle 'pwsh -NoProfile -File ./scripts/validate-skill-templates.ps1 -Ref HEAD' } +Add-ValidationResult -Results $results -Name 'Deprecated skill-creator-agnostic contract stays explicit' -Action { + $agents = Get-FileText -RepoRoot $repoRoot -RelativePath 'AGENTS.md' -GitRef $Ref + $readme = Get-FileText -RepoRoot $repoRoot -RelativePath 'README.md' -GitRef $Ref + $skill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/skill-creator-agnostic/SKILL.md' -GitRef $Ref + $evals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/skill-creator-agnostic/evals/evals.json' -GitRef $Ref + + Assert-Contains -Name 'AGENTS.md' -Content $agents -Needle '`skill-creator-agnostic` is deprecated, no longer maintained, and retained only for backward compatibility until 1.0.0.' + Assert-Contains -Name 'AGENTS.md' -Content $agents -Needle 'Agents must not use it for new skill creation, skill modification, or benchmarking; use Anthropic''s `skill-creator` directly and apply the repository-specific requirements from this `AGENTS.md`.' + Assert-Contains -Name 'README.md' -Content $readme -Needle '`skill-creator-agnostic` is intentionally omitted from the recommended always-on install list.' + Assert-Contains -Name 'README.md' -Content $readme -Needle '| [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | **⚠️ Deprecated**' + Assert-Contains -Name 'README.md' -Content $readme -Needle 'Do not install it for new work; use Anthropic `skill-creator` and apply the repository rules in `AGENTS.md`.' + Assert-Contains -Name 'skill-creator-agnostic/SKILL.md' -Content $skill -Needle 'DEPRECATED — no longer maintained and scheduled for removal in 1.0.0.' + Assert-Contains -Name 'skill-creator-agnostic/SKILL.md' -Content $skill -Needle '> [!CAUTION]' + Assert-Contains -Name 'skill-creator-agnostic/SKILL.md' -Content $skill -Needle 'Use Anthropic `skill-creator` + `AGENTS.md` instead.' + Assert-Contains -Name 'skill-creator-agnostic/SKILL.md' -Content $skill -Needle 'Do not continue or recommend the historical `skill-creator-agnostic` workflow as an alternative implementation.' + Assert-NotContains -Name 'skill-creator-agnostic/SKILL.md' -Content $skill -Needle '## Workflow' + Assert-Contains -Name 'skill-creator-agnostic/evals/evals.json' -Content $evals -Needle 'Anthropic skill-creator' + Assert-Contains -Name 'skill-creator-agnostic/evals/evals.json' -Content $evals -Needle 'no longer maintained' + Assert-Contains -Name 'skill-creator-agnostic/evals/evals.json' -Content $evals -Needle '1.0.0' + Assert-Contains -Name 'skill-creator-agnostic/evals/evals.json' -Content $evals -Needle 'Does not recommend skill-creator-agnostic as a companion or alternative implementation' +} + Add-ValidationResult -Results $results -Name 'App skill collects target framework and conditional web_variant' -Action { $forms = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/dotnet-new-app-slnx/FORMS.md' -GitRef $Ref Assert-Contains -Name 'dotnet-new-app-slnx/FORMS.md' -Content $forms -Needle '### target_framework' @@ -1442,6 +1464,45 @@ Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates } } +Add-ValidationResult -Results $results -Name 'Git summary skills reduce ranges to surviving final-state outcomes before using history' -Action { + $changelogSkill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-keep-a-changelog/SKILL.md' -GitRef $Ref + $changelogEvals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-keep-a-changelog/evals/evals.json' -GitRef $Ref + $nugetSkill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-nuget-release-notes/SKILL.md' -GitRef $Ref + $nugetEvals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-nuget-release-notes/evals/evals.json' -GitRef $Ref + $squashSkill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-squash-summary/SKILL.md' -GitRef $Ref + $squashEvals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-squash-summary/evals/evals.json' -GitRef $Ref + $readme = Get-FileText -RepoRoot $repoRoot -RelativePath 'README.md' -GitRef $Ref + + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $changelogSkill -Needle 'History is evidence; the resulting state is truth.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $changelogSkill -Needle 'Reduce first. Interpret second. Summarize last.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $changelogSkill -Needle 'Base absent and `HEAD` absent -> omit it.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $changelogSkill -Needle 'Do not summarize commits one by one and deduplicate the prose afterward.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $changelogSkill -Needle 'Use history only to explain the surviving outcomes' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $changelogEvals -Needle 'Omits `Foo` because it leaves no surviving base-to-HEAD change' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $changelogEvals -Needle 'Does not add a Security or other section entry when the final diff contradicts the commit message claim' + + Assert-Contains -Name 'git-nuget-release-notes/SKILL.md' -Content $nugetSkill -Needle 'History is evidence; the resulting state is truth.' + Assert-Contains -Name 'git-nuget-release-notes/SKILL.md' -Content $nugetSkill -Needle 'Do not accumulate bullets from individual commits and deduplicate them afterward.' + Assert-Contains -Name 'git-nuget-release-notes/SKILL.md' -Content $nugetSkill -Needle '`Newtonsoft.Json 13.0.3 -> 14.0.0 -> 13.0.3` -> no `# ALM` bullet.' + Assert-Contains -Name 'git-nuget-release-notes/SKILL.md' -Content $nugetSkill -Needle 'Read the full commit bodies only after the cumulative delta is clear.' + Assert-Contains -Name 'git-nuget-release-notes/SKILL.md' -Content $nugetSkill -Needle 'A restored API or reverted dependency upgrade does not earn a section entry.' + Assert-Contains -Name 'git-nuget-release-notes/evals/evals.json' -Content $nugetEvals -Needle 'Omits the reverted `Newtonsoft.Json` change because the final version matches the base state' + Assert-Contains -Name 'git-nuget-release-notes/evals/evals.json' -Content $nugetEvals -Needle 'Does not claim a breaking API removal for `WidgetClient.LegacySend()` because it was restored unchanged' + + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $squashSkill -Needle 'This skill answers one question: **What would this branch effectively do if it were squashed into one commit now?**' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $squashSkill -Needle 'History is evidence; the resulting state is truth.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $squashSkill -Needle 'Do not classify commit 1, then commit 2, then commit 3 and merge duplicate prose afterward.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $squashSkill -Needle 'A dependency or version that returns to the base value does not deserve a retained line.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $squashSkill -Needle 'Does this exact change survive from base to `HEAD`?' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $squashEvals -Needle 'Omits the `Microsoft.NET.Test.Sdk` change because the final version returns to `18.6.0`' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $squashEvals -Needle 'Omits `Foo` entirely because it is absent at both the base and `HEAD` states' + + Assert-Contains -Name 'README.md' -Content $readme -Needle 'reduces the selected range to surviving base-to-`HEAD` outcomes before section classification' + Assert-Contains -Name 'README.md' -Content $readme -Needle 'reduces each package to its surviving base-to-`HEAD` delta before classifying history' + Assert-Contains -Name 'README.md' -Content $readme -Needle 'reducing the cumulative base-to-`HEAD` delta first so reverted churn disappears' + Assert-Contains -Name 'README.md' -Content $readme -Needle '**Final-state first** — computes the cumulative base-to-`HEAD` delta before reading chronology' +} + Add-ValidationResult -Results $results -Name 'Rendered app worker template leaves no unexpected placeholders' -Action { $files = @( 'skills/dotnet-new-app-slnx/assets/shared/Directory.Packages.props', From 706ee50a9af78f9491d58606603e6edc104b2ef4 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:45 +0200 Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=93=9D=20update=20readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update repository README to reflect skill changes, deprecations, and recent improvements. Maintain accurate documentation of available skills and their status. --- README.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index c38a7ea..724bdf2 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,6 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-keep-a-changel npx skills add https://github.com/codebeltnet/agentic --skill git-nuget-release-notes npx skills add https://github.com/codebeltnet/agentic --skill git-nuget-readme npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-summary -npx skills add https://github.com/codebeltnet/agentic --skill skill-creator-agnostic npx skills add https://github.com/codebeltnet/agentic --skill markdown-illustrator npx skills add https://github.com/codebeltnet/agentic --skill git-repo-digest npx skills add https://github.com/codebeltnet/agentic --skill trunk-first-repo @@ -87,6 +86,8 @@ npx skills add https://github.com/codebeltnet/agentic --skill agent-smith # npx skills add https://github.com/codebeltnet/agentic --skill another-skill ``` +`skill-creator-agnostic` is intentionally omitted from the recommended always-on install list. It is **⚠️ Deprecated**, no longer maintained, and scheduled for removal in **1.0.0**; use Anthropic `skill-creator` plus this repository's `AGENTS.md` instead. + ### Scoping options | Location | Scope | When to use | @@ -104,11 +105,11 @@ npx skills add https://github.com/codebeltnet/agentic --skill agent-smith | Skill | Description | |-------|-------------| | [git-visual-commits](skills/git-visual-commits/SKILL.md) | AI-driven git commit workflow with deterministically validated emoji-first subjects (gitmoji-first), optional conventional prefixes only on explicit request, and three identity modes: bot-attributed (`git bot commit`), human-attributed (`git commit`), and collaborative (`git our commit` — agent analyzes authorship, human picks attribution). Its first critical rule requires a complete SKILL.md read through EOF, then a bundled PowerShell gate rejects unapproved emoji, anything other than one separator space, uppercase description beginnings, and subjects over 70 characters before plan display and immediately before Git. Multi-file plans that initially collapse to one category also require a visible full-context quality gate; one-file changes keep the fast path. Includes commit body by default (opt out with `no-body`), semantic intent splitting, clarification-before-correction safety, and auto-approval mode (`yolo` / `auto`) that cannot bypass validation. Stack-agnostic. | -| [git-keep-a-changelog](skills/git-keep-a-changelog/SKILL.md) | Git-aware Keep a Changelog companion that creates or updates `CHANGELOG.md` from the current branch by default. A bundled deterministic resolver separates branch-unique commit history from merge-base-to-`HEAD` net diffs, excludes the previous-release or comparison boundary for both concrete releases and `[Unreleased]`, and fails if commits already reachable from the comparison branch bleed into the selected scope. It inspects dependency and version manifests before commit bodies, treats the selected branch or explicit range as author-agnostic so all PR contributors remain included, infers a release heading from a branch version hint like `v0.3.0/...`, asks a mandatory `Yes / No / Custom` question before including pending worktree changes in ordinary concrete-release drafts, and keeps yolo/auto limited to automatic staged, unstaged, and untracked inclusion without widening committed history. It also creates missing changelogs, writes required SemVer-aware highlights, maintains compare-link footers, preserves natural prose wrapping, and curates standard Keep a Changelog sections instead of dumping raw commit logs. | -| [git-nuget-release-notes](skills/git-nuget-release-notes/SKILL.md) | Git-aware NuGet release-notes companion for .NET repos that keep cumulative `.nuget/{ProjectName}/PackageReleaseNotes.txt` files. Discovers packable `src/` projects, resolves concrete package version and availability, creates missing files when needed, and writes per-package `ALM` / `Breaking Changes` / `New Features` / `Improvements` / `Bug Fixes` style notes from full commit context plus the net diff instead of dumping commit subjects. | +| [git-keep-a-changelog](skills/git-keep-a-changelog/SKILL.md) | Git-aware Keep a Changelog companion that creates or updates `CHANGELOG.md` from the current branch by default. A bundled deterministic resolver separates branch-unique commit history from merge-base-to-`HEAD` net diffs, excludes the previous-release or comparison boundary for both concrete releases and `[Unreleased]`, and fails if commits already reachable from the comparison branch bleed into the selected scope. It reduces the selected range to surviving base-to-`HEAD` outcomes before section classification, inspects dependency and version manifests before commit bodies, treats the selected branch or explicit range as author-agnostic so all PR contributors remain included, infers a release heading from a branch version hint like `v0.3.0/...`, asks a mandatory `Yes / No / Custom` question before including pending worktree changes in ordinary concrete-release drafts, and keeps yolo/auto limited to automatic staged, unstaged, and untracked inclusion without widening committed history. It also creates missing changelogs, writes required SemVer-aware highlights, maintains compare-link footers, preserves natural prose wrapping, and curates standard Keep a Changelog sections instead of dumping raw commit logs. | +| [git-nuget-release-notes](skills/git-nuget-release-notes/SKILL.md) | Git-aware NuGet release-notes companion for .NET repos that keep cumulative `.nuget/{ProjectName}/PackageReleaseNotes.txt` files. Discovers packable `src/` projects, resolves concrete package version and availability, creates missing files when needed, reduces each package to its surviving base-to-`HEAD` delta before classifying history, and writes per-package `ALM` / `Breaking Changes` / `New Features` / `Improvements` / `Bug Fixes` style notes from final package state plus supporting commit context instead of dumping commit subjects. | | [git-nuget-readme](skills/git-nuget-readme/SKILL.md) | Git-aware NuGet README companion for .NET repos that advertise a package from `src/`. Resolves the real packable project the README should sell, combines git history with actual package metadata, source capabilities, and relevant tests when feasible, preserves honest badge/docs/contributing sections, and writes a forthcoming, adoption-friendly `README.md` with repo-derived branding, clear value, install, framework-support, and quick-start guidance. | -| [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns the full current feature branch into a curated set of compact lowercase-start summary lines for PR or squash-and-merge contexts by default, comparing against the repository base branch rather than a same-named tracking remote, including commits from all authors unless explicitly narrowed, preserving technical identifiers, merging overlap, dropping low-signal noise, retaining dependency and version-pin changes as hard-rule semantic groups before net-effect collapsing, highlighting distinct meaningful efforts, and avoiding changelog-style wording, unsupported claims, yolo prompts, needless commit-range questions, or commit-selection UI for ordinary branch-level squash requests. | -| [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | Runner-agnostic overlay for Anthropic `skill-creator`. Adds repo and environment guardrails for skill authoring and benchmarking: temp-workspace isolation, `iteration-N/eval-name/{config}/run-N/` benchmark layout, valid `grading.json` summaries, generated `benchmark.json`, honest `MEASURED` vs `SIMULATED` labeling, and sync/README discipline for repo-managed skills. | +| [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns the full current feature branch into a curated set of compact lowercase-start summary lines for PR or squash-and-merge contexts by default, comparing against the repository base branch rather than a same-named tracking remote, including commits from all authors unless explicitly narrowed, reducing the cumulative base-to-`HEAD` delta first so reverted churn disappears, preserving technical identifiers, merging overlap, keeping surviving dependency/version changes separate from build/refactor work when the final diff still shows them, and avoiding changelog-style wording, unsupported claims, yolo prompts, needless commit-range questions, or commit-selection UI for ordinary branch-level squash requests. | +| [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | **⚠️ Deprecated** — no longer maintained and retained only for backward compatibility until **1.0.0**. Do not use it for new skill-authoring work; use Anthropic `skill-creator` together with this repository's `AGENTS.md`. | | [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. | | [git-repo-digest](skills/git-repo-digest/SKILL.md) | Turns any full repository URL into a deterministic digest workspace using the bundled .NET file-based runner `scripts/digest.cs`. Requires explicit `--repo-url`, resolves omitted output paths to `/.bot/digests` and passes that as `--output-root`, maps multiple positional URLs the same way for slash commands, bare pasted URLs, and natural-language requests by treating the first URL as the digest repo and every later URL as repeated `--external-repo-url`, always writes into `{output-root}/{repo-id}/{yyyyMMdd-HHmmssZ}`, accepts repeated curated public consumer repos, derives `{repo-id}`, fixes `result/`, performs shallow git clones, packs local tracked files with the bundled C# packer using `git ls-files`, separates XML evidence into `source.xml`, `tests.xml`, `projects.xml`, editorial `readmes.xml`, and scenario-only `external-usage.xml`, writes package and conceptual overview prompts under `prompts/`, emits public API summaries, engineering signals, evidence indexes, ordered XML chunks, referenced-package evidence maps for aggregate examples, and manifest-backed frontmatter hints, treats previous digest prose as contamination during fresh generation, then guides the agent to fully read the current phase's required evidence before writing package digests and a concept-led `result/Index.md` with YAML frontmatter containing Product-derived overview title metadata, validated documentation URLs resolved from PackageProjectUrl, documentation-host-filtered exact `.nuget//README.md` documentation links including emoji-prefixed Documentation headings and "More documentation..." blocks, DocFX `metadata[].dest` API paths, and source namespace page candidates from `src//**/*.cs`, target frameworks, package/library counts, external links, package-family links, and context glyphs, and validates authored result examples with `--validate-results` as a deterministic API-shape, Codebelt.Extensions.Xunit shape, PascalCase `MethodName_Scenario_ExpectedBehavior` test-method naming, Basic usage quality, and optimized NuGet-backed executable test gate with bounded parallelism. | | [dotnet-new-lib-slnx](skills/dotnet-new-lib-slnx/SKILL.md) | Scaffold a new .NET NuGet library solution following codebeltnet engineering conventions. Dynamic defaults for TFM/repository metadata, latest-stable NuGet package resolution, tuning projects plus a tooling-based benchmark runner, TFM-aware test environments, strong-name signing, NuGet packaging, DocFX documentation, CI/CD pipeline, and code quality tooling. | @@ -155,12 +156,14 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-nuget-readme npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-summary ``` -`skill-creator-agnostic` +`skill-creator-agnostic` **⚠️ Deprecated — legacy compatibility only** ```bash npx skills add https://github.com/codebeltnet/agentic --skill skill-creator-agnostic ``` +No longer maintained. Scheduled for removal in **1.0.0**. Do not install it for new work; use Anthropic `skill-creator` and apply the repository rules in `AGENTS.md`. + `markdown-illustrator` ```bash @@ -279,7 +282,8 @@ Sometimes the history is already written and the only thing you need is the fina - **No yolo prompt** — the skill is read-only, so it acts directly without asking for auto-approval language from mutating workflows - **No commit-picker UX** — ordinary branch-level squash requests do not become commit-selection questions or widgets; the skill resolves the branch scope and writes the summary - **Distinct efforts stay distinct** — preserves meaningful change groups instead of forcing one umbrella line -- **Dependency updates stay explicit** — package/version baseline changes and version pins are hard-rule retained groups, even when later commits revert or adjust them, and never get absorbed into generic build-system or refactor wording +- **Final-state first** — computes the cumulative base-to-`HEAD` delta before reading chronology, so reverted experiments and temporary implementations disappear +- **Surviving dependency truth** — package/version changes stay explicit when they survive in the final diff and disappear entirely when they return to the base value - **Intent over chronology** — collapses noisy commit stacks into the retained grouped effort - **Low-signal noise gets dropped** — typo-only and trivial fixup churn do not deserve their own lines - **Late release-prep commits stay in scope** — changelog, version-bump, and release-finalization follow-ups are treated as part of the branch by default and then merged or dropped during semantic collapsing @@ -295,6 +299,7 @@ Writing `CHANGELOG.md` well is harder than it looks. Raw commit subjects are too - **Keep a Changelog first** — writes `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security` sections in the expected style - **Full-commit context** — reads complete commit messages and the net diff before writing +- **History is evidence, result is truth** — reduces the selected range to surviving base-to-`HEAD` outcomes before section classification, so reverted work disappears and one surviving capability is described once - **Deterministic release isolation** — resolves the real comparison branch, excludes its merge boundary, and verifies that no commit already on the base branch can bleed into the new release - **PR-complete history** — keeps every branch-unique commit from every contributor while avoiding a same-name feature tracking ref as the comparison base - **Cumulative dependency coverage** — when version manifests changed across the release range, diffs them from base to `HEAD` so the changelog reflects the surviving package/version story instead of only per-commit fragments @@ -318,6 +323,8 @@ Repo-wide changelogs are useful, but NuGet packages often need package-scoped re - **Per-package, not repo-wide** — writes one truthful release block per publishable assembly/package - **Concrete package metadata** — resolves `Version:` and `Availability:` from the branch/project instead of inventing placeholders +- **Package delta first** — resolves public APIs, dependency versions, TFMs, and package metadata from base to `HEAD` before using history as supporting context +- **Reverted churn disappears** — temporary upgrades, removed-then-restored APIs, and other cancelled work do not reach the final release block - **Current codebelt format** — follows the established `ALM`, `Breaking Changes`, `New Features`, `Improvements`, `Bug Fixes`, and optional `References` blueprint - **Missing-file aware** — can create `.nuget/{ProjectName}/PackageReleaseNotes.txt` when a packable project should be represented - **History-aware** — preserves cumulative newest-first package history instead of overwriting older entries @@ -337,20 +344,15 @@ Choosing a NuGet package often happens fast: a developer lands on the README, sc - **Preserve the good parts** — keeps accurate badges, docs links, contributing guidance, and license sections when they are already working - **Not a changelog in disguise** — uses git history for context but writes adoption-oriented README copy instead of replaying commit subjects -### Why skill-creator-agnostic? +### Why skill-creator-agnostic is deprecated -Anthropic's `skill-creator` is an excellent base workflow, but the day-to-day friction usually comes from the environment around it: different runners, Windows/PowerShell encoding traps, benchmark layout mistakes, and the temptation to present a synthetic pipeline check as if it were a measured model benchmark. +`skill-creator-agnostic` is now a legacy compatibility artifact, not an active skill-authoring workflow. It is **⚠️ Deprecated**, no longer maintained, and scheduled for removal in **1.0.0**. -**skill-creator-agnostic** keeps the upstream workflow intact and adds the parts teams actually trip over when they want the same skill to hold up across Codex, GitHub Copilot, Opus, and similar agents. +For new skill creation, modification, and benchmarking: -- **Overlay, not fork** — treats Anthropic `skill-creator` as the base and layers repo/runtime guardrails on top -- **Runner-agnostic by design** — chooses from available execution capability instead of assuming one vendor CLI -- **Benchmark-contract aware** — enforces `iteration-N/eval-name/{config}/run-N/`, valid `grading.json.summary`, and generated `benchmark.json` -- **Tool-path explicit** — points authors to the installed Anthropic `skill-creator` copy that provides `scripts/aggregate_benchmark.py` and `eval-viewer/generate_review.py` -- **Honest benchmark modes** — keeps `MEASURED` and `SIMULATED` runs clearly separated so pipeline validation never masquerades as model quality -- **PowerShell-safe** — calls out UTF-8 no BOM, `PYTHONUTF8`, stable counting, provider-path normalization, prompt-passing pitfalls, and other Windows-specific benchmark traps -- **Codex-friendly benchmarking** — treats Codex CLI as a valid real runner when present, preserves `MEASURED` parity honestly, uses raw event output as fallback evidence when convenience files are missing, and prefers parallel paired runs when the runner supports sub-agents -- **Repo-managed discipline** — keeps per-skill evals, local-install sync, and README updates in scope for first-party skills +- Use Anthropic `skill-creator` directly +- Apply this repository's skill-authoring, eval, sync, and validation rules from `AGENTS.md` +- Do not treat `skill-creator-agnostic` as a fallback, overlay, or parallel implementation ### Why git-repo-digest? From 85d49e633645f48f47283181d903110d1e31b390 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:07:49 +0200 Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=92=AC=20release=20notes=20for=20v0.9?= =?UTF-8?q?.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document breaking changes, new features, improvements, and deprecations in this release. Reflects skill enhancements, governance updates, and deprecation of skill-creator-agnostic. --- CHANGELOG.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 019a7a4..7b19e68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,64 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.8.2] - 2026-08-07 + +This is a patch release focused on skill refinement and documentation hardening. The release significantly expands `git-keep-a-changelog` with step-by-step workflow improvements, strengthens `git-nuget-release-notes` and `git-visual-squash-summary` skills, deprecates `skill-creator-agnostic` in favor of the upstream Anthropic `skill-creator`, enhances skill validation tooling, and improves repository guidance documentation in `AGENTS.md` and `README.md`. + +### Added + +- Comprehensive step-by-step workflow sections in `git-keep-a-changelog` covering release-scope resolution, changelog-target determination, pending-worktree-change confirmation gates, cumulative-result inspection, release classification, content curation, and careful changelog editing, +- Deterministic reduction model in `git-keep-a-changelog` for semantic-delta analysis using cumulative manifests and net diffs before commit-body interpretation, with detailed reconciliation rules to avoid duplicate or conflicting changelog entries, +- Release highlight contract in `git-keep-a-changelog` requiring every concrete release entry to open with a human-written paragraph that explicitly classifies the release as `major`, `minor`, or `patch`, with optional warning callouts for migration risk, +- Mandatory checkpoint enforcement in `git-keep-a-changelog` including release-isolation verification, base-history-bleed detection, release-highlight presence, and bullet-punctuation consistency before completing edits, +- Enhanced `git-keep-a-changelog` good and bad output characteristics sections documenting silent-boundary inclusion as a critical failure mode, proper use of `history_range` and `diff_range`, comprehensive commit-body reading, and complete changelog maintenance, +- Expanded `git-keep-a-changelog` user-intent vs. gates guidance clarifying that yolo/auto mode bypasses the Step 3 confirmation gate but never widens committed history or changes Git range inclusivity, +- New eval coverage for `git-keep-a-changelog` including deterministic reduction model validation, reconciliation rule verification, manifest-diff prioritization, pending-change handling, and step-by-step workflow validation, +- Enhanced `git-nuget-release-notes` skill with improved guidance on per-package release notes generation from git history and manifest deltas, +- Expanded `git-nuget-release-notes` eval coverage documenting package discovery, release version resolution, cumulative-history preservation, and per-assembly changelog generation patterns, +- Enhanced `git-visual-squash-summary` skill documentation with improved commit-language reference compliance and semantic-grouping guidance, +- Expanded `git-visual-squash-summary` eval coverage documenting author-neutral scope, base-branch resolution, commit-grouping validation, and curated-summary quality standards, +- Enhanced `scripts/validate-skill-templates.ps1` with improved skill content validation, SKILL.md structure verification, and asset consistency checking, +- Deprecation notice for `skill-creator-agnostic` with clear redirect to Anthropic's `skill-creator` and repository-specific `AGENTS.md` guidance. + +### Changed + +- Refactored `git-keep-a-changelog` SKILL.md with new mandatory workflow sections (Steps 1–8) replacing implicit procedures with explicit, checkpointed guidance for all changelog-generation paths, +- Enhanced `git-keep-a-changelog` yolo/auto mode documentation to clarify that full autonomy applies only to pending-worktree decisions, never to committed-history scope or range inclusivity, +- Restructured `git-keep-a-changelog` non-negotiable rules to emphasize deterministic scope resolution, git-history authority, author-agnostic scope by default, and mandatory release highlights, +- Updated `git-keep-a-changelog` Step 3 confirmation-gate guidance to clarify plain-text fallback paths when native structured input is unavailable, with mandatory `Yes / No / Custom` meaning preserved across both paths, +- Expanded `git-keep-a-changelog` Step 3b release-isolation verification to require explicit base-history-bleed detection and boundary-commit validation before proceeding, +- Reorganized `git-keep-a-changelog` Step 4 into explicit sub-steps (4a–4f) with clear sequencing: base-commit inspection, manifest detection, cumulative manifest-diff inspection, approved pending-change inspection, surviving-outcome determination, and chronological commit-body reading, +- Enhanced `git-keep-a-changelog` reconciliation rules with detailed examples showing how churn elimination and surviving-outcome classification prevent duplicate changelog entries, +- Updated README.md descriptions for `git-keep-a-changelog`, `git-nuget-release-notes`, and `git-visual-squash-summary` to reflect enhanced skill guidance and workflow improvements, +- Simplified `skill-creator-agnostic` SKILL.md to a deprecation shim with only redirect guidance, removing all deprecated workflow documentation, +- Updated AGENTS.md with explicit deprecation notice for `skill-creator-agnostic` and clear directive to use Anthropic's `skill-creator` with repository `AGENTS.md` rules, +- Enhanced AGENTS.md third-party-skills guidance to clarify that companion overlays around third-party skills must not be created; instead, document repo-specific behavior in `AGENTS.md` itself. + +### Deprecated + +- `skill-creator-agnostic` is now explicitly deprecated, no longer maintained, and retained only for backward compatibility until **1.0.0**; new skill creation, modification, and benchmarking should use Anthropic's `skill-creator` directly together with the repository rules in `AGENTS.md`. + +## [0.8.1] - 2026-08-01 + +This is a patch release focused on agent-smith refinement, skill-validator hardening, and improved git-visual-commits quality gating. The release refactors agent-smith guidance for conciseness and parallelism, introduces skill-template validators to the repository, hardens the git-visual-commits single-category quality gate, and clarifies auto-approval triggering behavior with new eval coverage. + +### Added + +- Skill template validators in `scripts/validate-skill-templates.ps1` that check skill directory structure, SKILL.md frontmatter, description completeness, FORMS.md usage patterns, eval coverage, and cross-reference consistency, +- Deterministic skill content validation including presence of required `name` and `description` fields, YAML frontmatter correctness, file-extension consistency, and description character-count verification, +- New `skills/agent-smith/references/skill-authoring.md` reference document providing comprehensive skill-creation guidance covering real-task grounding, repository inspection, parallelism mapping, sequential-constraint identification, script-language selection with .NET-first defaults, evaluation workflow, and required authoring-feedback elements, +- Eval cases documenting skill validation behavior, template consistency checking, and edge-case handling across repo-managed skills, +- Enhanced eval coverage for `agent-smith` and `git-visual-commits` including new single-category quality-gate scenarios, auto-approval edge cases, and subject-validation lock verification. + +### Changed + +- Refactored `agent-smith` SKILL.md with improved guidance on conciseness, parallelism identification, task-graph mapping, and sequential-vs-concurrent constraint analysis, +- Enhanced `agent-smith` section organization for clearer progressive disclosure of domain-specific guidance across engineering disciplines, +- Refined `git-visual-commits` SKILL.md with improved single-category quality gate documentation, clarifying when multi-file changes collapse to one semantic category and when the gate requires full-context review, +- Enhanced `git-visual-commits` auto-approval triggering documentation to explicitly document yolo/auto mode and when auto-approval bypasses confirmation steps, +- Updated README.md with improved descriptions for `agent-smith` and `git-visual-commits` highlighting new skill-validation capabilities and quality-gate refinements. + ## [0.8.0] - 2026-07-18 This is a minor release introducing the `agent-smith` skill for rigorous software-craftsmanship standards across design, architecture, implementation, testing, performance, security, DevSecOps, and CI/CD, alongside the `dotnet-benchmark` skill for evidence-driven performance testing. The release resolves a critical git-keep-a-changelog bug that could silently include already-released commits when determining scope boundaries, replaces implicit caret notation with deterministic branch-derived scope validation, and introduces deterministic commit-subject validation infrastructure to `git-visual-commits` with a bundled PowerShell validator and full-skill-read gating. PowerShell execution is standardized to pwsh 7+, and skill validation tooling is strengthened across the repository. @@ -494,6 +552,8 @@ This is a minor release that introduces two complementary git workflow skills, e - Improved scaffold fidelity with hidden `.bot` asset preservation, explicit UTF-8 and BOM handling, and checks aimed at preventing mojibake or incomplete generated output. [Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.8.0...HEAD +[0.8.2]: https://github.com/codebeltnet/agentic/compare/v0.8.1...v0.8.2 +[0.8.1]: https://github.com/codebeltnet/agentic/compare/v0.8.0...v0.8.1 [0.8.0]: https://github.com/codebeltnet/agentic/compare/v0.7.5...v0.8.0 [0.7.5]: https://github.com/codebeltnet/agentic/compare/v0.7.4...v0.7.5 [0.7.4]: https://github.com/codebeltnet/agentic/compare/v0.7.3...v0.7.4 From f5860183b18519beef4659fdf56429b99b6d22f8 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 7 Aug 2026 17:09:28 +0200 Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=93=9D=20remove=20unreleased=20change?= =?UTF-8?q?log=20compare=20link?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b19e68..6bd261d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -551,7 +551,6 @@ This is a minor release that introduces two complementary git workflow skills, e - Improved scaffold fidelity with hidden `.bot` asset preservation, explicit UTF-8 and BOM handling, and checks aimed at preventing mojibake or incomplete generated output. -[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.8.0...HEAD [0.8.2]: https://github.com/codebeltnet/agentic/compare/v0.8.1...v0.8.2 [0.8.1]: https://github.com/codebeltnet/agentic/compare/v0.8.0...v0.8.1 [0.8.0]: https://github.com/codebeltnet/agentic/compare/v0.7.5...v0.8.0