From e8793631d68d611d24d3746f8174850c565542df Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Thu, 30 Jul 2026 18:43:52 +0200 Subject: [PATCH 1/7] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor=20agent-smith?= =?UTF-8?q?=20guidance=20for=20conciseness=20and=20parallelism?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructured skill to emphasize concise communication and bounded-concurrency assessment for independent retrieval and validation work. Added skill-authoring reference with guidance on progressive disclosure, tool batching, script selection, candidate-versus-baseline evaluation, and real-task grounding for AI agents authoring skills. --- skills/agent-smith/SKILL.md | 15 +++- skills/agent-smith/evals/evals.json | 16 +++++ .../agent-smith/references/skill-authoring.md | 71 +++++++++++++++++++ 3 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 skills/agent-smith/references/skill-authoring.md diff --git a/skills/agent-smith/SKILL.md b/skills/agent-smith/SKILL.md index 1532363..8a22b7a 100644 --- a/skills/agent-smith/SKILL.md +++ b/skills/agent-smith/SKILL.md @@ -1,7 +1,7 @@ --- name: agent-smith description: > - Apply a rigorous, consistent, evidence-driven software-craftsmanship standard across a whole engineering task. Invoke explicitly as `/agent-smith task`, or automatically for design, architecture, implementation, refactoring, review, API compatibility and Semantic Versioning, testing, benchmarking, performance, documentation, security and DevSecOps, CI/CD, delivery, governance, and engineering assessment. For .NET, also use when asked to fix specific IDE or CA diagnostics, clean up EditorConfig findings, make a solution code-style compliant, fix informational IDE diagnostics, or verify `dotnet format` conformance. It performs the requested work, respects repository conventions and user scope, validates before claiming completion, and reports evidence, trade-offs, and risk honestly. Technology-neutral at its core, with optional specialist guidance. Do NOT use for ordinary prose, casual conversation, translation, image generation, or unrelated factual questions. + Use this skill to apply a rigorous, evidence-driven software-craftsmanship standard across an engineering task. Invoke explicitly as `/agent-smith task`, or automatically for architecture, implementation, refactoring, review, API compatibility and Semantic Versioning, testing, benchmarking, performance, skill authoring, documentation, security and DevSecOps, CI/CD, delivery, governance, and engineering assessment. For .NET, also use for IDE or CA diagnostic remediation, EditorConfig cleanup, code-style compliance, informational diagnostics, and `dotnet format` conformance. Perform the requested work, respect repository scope and conventions, validate before completion, and report evidence and risk honestly. Technology-neutral core; specialist guidance loads on demand. Do NOT use for ordinary prose, casual conversation, translation, image generation, or unrelated factual questions. --- # Agent Smith @@ -16,6 +16,12 @@ Apply **one coherent engineering standard** across design, implementation, valid The standard is technology-neutral. Specialist guidance (including .NET, Git, GitHub, CI/CD, REST, and software-supply-chain security) is loaded only when the task calls for it, and is never imposed on work where it does not apply. +## Critical skill-authoring lock + +When creating, modifying, reviewing, or evaluating a skill, read `references/skill-authoring.md` before editing. Inspect the actual skill, applicable repository instructions, real execution traces, repeated work, and failure evidence before recommending changes; if unavailable, make that inspection the first required step. Always analyze the task graph for safe parallelism and concurrency. State how independent retrieval, execution, validation, and grading can use bounded fan-out; encode it in the skill when useful. Keep dependencies, shared mutations, rate-limited calls, and fragile ordered workflows sequential. + +For non-trivial reusable scripts and deterministic validators bundled with a skill, choose C# and .NET by default in this .NET-first skill collection. Cross-repository portability alone is not a reason to retain or introduce Python, Bash, or PowerShell. Use another language only for a concrete repository/host constraint, vendor SDK, or materially simpler native operation; state the evidence. Resolve the latest supported .NET LTS dynamically from Microsoft's official support policy when compatible repository SDK/target-framework pins or explicit user constraints do not decide. Do not replace a simpler native command with a C# program merely to satisfy the preference. + ## Critical .NET conformance lock When the task selects .NET EditorConfig conformance mode, read both `references/dotnet.md` and `references/dotnet-editorconfig-conformance.md` from the activated skill directory before the first formatter command. Do not search for those resources relative to the target repository or improvise the workflow if a required reference cannot be read. @@ -77,6 +83,7 @@ A task may select **multiple** modes. Load core principles for every invocation, | Security & DevSecOps | identity, authorization, secrets, dependencies, pipelines, supply chain, permissions, deployment security | `references/security-and-devsecops.md` | | Delivery & repository engineering | CI/CD, Git, branching, repo structure, releases, automation, containers, deployment | `references/delivery-and-repositories.md` | | Documentation | public API docs, README, architecture docs, guides, release notes, examples, DocFX | `references/documentation.md` | +| Skill authoring | creating, modifying, reviewing, describing, or evaluating agent skills and their bundled resources | `references/skill-authoring.md` | | Governance | policies, standards, compliance, metrics, enterprise repo governance, guardrails | `references/governance.md` | **Load .NET guidance only when .NET or C# is actually relevant.** For non-.NET work, apply the core principles and let local conventions govern language-specific detail. @@ -87,6 +94,7 @@ A task may select **multiple** modes. Load core principles for every invocation, - **Benchmark assessment**: core principles + decision framework + performance + implementation + platform reference (e.g. `dotnet.md`) + response contract; agent-handoff template only if delegation is requested. - **Public API review**: core principles + decision framework + api-design-and-compatibility + implementation + platform reference + documentation + response contract. - **CI/CD pipeline**: core principles + decision framework + security-and-devsecops + delivery-and-repositories + governance (when policy is involved) + response contract. +- **Skill authoring**: core principles + decision framework (for material choices) + skill authoring + implementation/testing/documentation as applicable. Make concurrency and script-runtime choices explicit. - **Scoped .NET diagnostic remediation** (`/agent-smith fix the named IDE and CA diagnostics in src/Codebelt.Core`): core principles + implementation + .NET + .NET EditorConfig conformance + testing. Preserve the user-supplied diagnostic IDs and path through discovery, edits, final verification, build, tests, and reporting. ## Repository precedence @@ -122,7 +130,7 @@ For each material finding: Issue → Why it matters → Evidence or reasoning ## Response behaviour -Be direct, respectful, and technically defensible. Challenge weak assumptions; preserve good existing decisions; prioritize material issues; avoid empty praise; distinguish recommendation from requirement; avoid exaggerated certainty; explain trade-offs; and avoid unnecessary verbosity for trivial work. +**Be concise. Sacrifice grammar for the sake of concision.** Prefer clear fragments when they shorten feedback. Remain respectful and technically defensible. Challenge weak assumptions; preserve good existing decisions; prioritize material issues; avoid empty praise; distinguish recommendation from requirement; avoid exaggerated certainty; explain non-obvious trade-offs. Never omit required evidence, validation limits, blockers, compatibility impact, or material risk. For substantial assessments, use the structure in `references/response-contract.md` (Assessment → Findings → Recommendation → Trade-offs → Validation → Actionable handoff). Do not force that structure onto every response. When producing a formal assessment or a delegation prompt, use `references/engineering-assessment-template.md` or `references/agent-handoff-template.md`. @@ -154,7 +162,7 @@ This skill must not: - turn every small task into an architecture exercise; - produce advice without completing the requested work when implementation is possible; - fabricate evidence or claim unperformed validation; -- optimize solely for terseness; +- sacrifice correctness, required evidence, or material context for terseness; - broaden the task without justification; - introduce dependencies or abstractions without demonstrating value. @@ -174,6 +182,7 @@ Load on demand, per the routing table: - `references/security-and-devsecops.md` — identity, secrets, dependencies, pipelines, supply chain. - `references/delivery-and-repositories.md` — CI/CD, Git, releases, repository engineering. - `references/documentation.md` — documentation as part of the product. +- `references/skill-authoring.md` — skill design, parallelism, .NET-first scripts, descriptions, and eval loops. - `references/governance.md` — policies, standards, and metrics (Intent → Drivers → Metrics → Actions). - `references/response-contract.md` — review severity, finding shape, and assessment structure. - `references/engineering-assessment-template.md` — fill-in template for a formal assessment. diff --git a/skills/agent-smith/evals/evals.json b/skills/agent-smith/evals/evals.json index 0c4eeb3..f3f6243 100644 --- a/skills/agent-smith/evals/evals.json +++ b/skills/agent-smith/evals/evals.json @@ -183,6 +183,22 @@ "After deliberate recovery, the response requires the artifact tool to report clean and reruns broad dotnet format against MultiTargeted.sln with --severity info and --verify-no-changes", "The response does not proceed to build or tests or claim completion while any artifact remains unsafe or detected" ] + }, + { + "id": 14, + "prompt": "/agent-smith improve our incident-research skill in this .NET-first repository family. It fetches twelve independent service endpoints sequentially, includes a reusable Python validator, has a long implementation-focused description, and has never been compared with a baseline. Keep the guidance reusable across our repositories and tell future agents how to validate the change.", + "expected_output": "A concise, evidence-driven skill-authoring workflow grounded in real traces and repository constraints. It explicitly maps safe bounded concurrency for independent fetches and eval work, preserves ordered or rate-limited operations, favors a C#/.NET validator using a dynamically resolved supported LTS when local pins do not decide, improves and tests the description as an activation contract, and requires clean-context candidate-versus-baseline evals with objective grading, timing, aggregation, and human review.", + "expectations": [ + "The response requires inspecting the existing skill, repository conventions, real execution traces, and failure evidence before rewriting generic guidance", + "The response identifies the twelve independent endpoint calls as concurrency candidates and recommends batching or bounded fan-out instead of sequential fetching", + "The response preserves sequential execution for real dependencies, shared mutations, rate limits, or fragile ordering and requires deterministic result ordering and attributable failures", + "The response recommends measuring elapsed time, cost or tokens, error rate, and output quality rather than assuming concurrency is faster", + "The response favors replacing the reusable Python validator with C# and .NET unless repository or host constraints justify another language", + "The response resolves the latest supported .NET LTS dynamically from Microsoft's official support policy when no compatible repository SDK or target-framework pin decides the version, rather than hardcoding a drifting release", + "The response treats the description as the activation contract, uses concise imperative user-intent wording, respects the 1,024-character limit, and tests realistic positive and near-miss triggers with repeated runs and a fixed train/validation split", + "The response requires realistic clean-context candidate-versus-original baseline evals, objective assertions with deterministic grading where possible, timing capture, benchmark aggregation, and human review", + "The feedback is concise and permits compact fragments without omitting validation limits, blockers, compatibility impact, or material risk" + ] } ] } diff --git a/skills/agent-smith/references/skill-authoring.md b/skills/agent-smith/references/skill-authoring.md new file mode 100644 index 0000000..f03914b --- /dev/null +++ b/skills/agent-smith/references/skill-authoring.md @@ -0,0 +1,71 @@ +# Skill authoring + +Load when creating, modifying, reviewing, describing, or evaluating agent skills. + +## Critical + +- Ground instructions in real tasks, repository artifacts, execution traces, corrections, and failure cases. Generic advice adds little value. +- Inspect the current skill, applicable repository instructions, execution traces, repeated helper work, and failures before choosing changes. When artifacts are unavailable, make this the first required action instead of treating a hypothetical design as confirmed. +- Always map the task graph. Identify independent reads, searches, API calls, executor runs, validators, and graders. Suggest bounded parallel execution and encode it when safe. +- Keep true dependencies, shared-file mutations, rate-limited operations, and fragile ordered workflows sequential. Parallelism must preserve deterministic outputs, stable ordering, error attribution, cancellation, and service limits. +- Batch independent retrieval through one multi-call request where the tool supports it. Otherwise fan out with an explicit concurrency bound. Avoid sequential fetching by habit. +- Measure the result. Compare elapsed time, tokens/cost, error rate, and output quality; do not assume concurrency improved the workflow. + +## .NET-first bundled scripts + +Choose C# and .NET by default for non-trivial reusable scripts, deterministic validators, data transformation, and orchestration in this .NET-first skill collection. Perceived cross-repository portability alone does not justify retaining or introducing Python, Bash, or PowerShell. + +1. Inspect repository SDK pins, target frameworks, existing script conventions, and supported execution hosts. +2. If no compatible local constraint decides the version, resolve the latest supported LTS from [Microsoft's official .NET support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). Do not hardcode a release that will drift. +3. Prefer a small C# file-based app when the supported SDK and host make it practical; use a minimal project only when dependencies or build behavior require one. +4. Preserve bounded concurrency, cancellation, deterministic ordering, actionable errors, and non-zero failure exits in script design. +5. Use another language only when an observed repository standard, host limitation, vendor SDK, or materially simpler native tool makes it the better engineering choice. State the evidence. + +Do not turn a one-line native command into a C# program. The preference applies where a bundled script provides reusable value. + +## Required authoring feedback + +Keep the response compact, but cover every item: + +- **Evidence** — inspected skill, repository rules, traces/repeated work, and failures; name anything unavailable. +- **Parallelism** — independent operations, concurrency bound, sequential constraints, deterministic ordering, failure attribution, cancellation, and rate limits. +- **Scripts** — C#/.NET default or the concrete evidence for an exception; SDK/target-framework resolution and validation behavior. +- **Description** — concise imperative user intent, trigger boundaries, 1,024-character gate, realistic positive and near-miss trigger tests, repeated runs, and fixed train/validation split. +- **Evaluation** — clean-context candidate-versus-original baseline, objective assertions, deterministic mechanical grading, timing/cost/error/quality metrics, aggregation, and human review. +- **Status** — commands and evidence actually produced; blockers, compatibility impact, validation limits, and material risk. + +## Skill content + +- Keep `SKILL.md` focused on instructions required on every activation. Move detailed, conditional material into directly linked references. +- Add what the agent would otherwise miss: domain procedures, project conventions, gotchas, defaults, failure handling, and validation loops. +- Prefer concise procedures over declarations. Give a clear default and a reasoned escape hatch instead of an unranked menu. +- Match control to fragility. Explain intent where judgment is safe; use exact commands and fail-closed gates where sequence or correctness is fragile. +- Bundle a tested script when execution traces show agents repeatedly recreating the same deterministic logic. + +See [Best practices for skill creators](https://agentskills.io/skill-creation/best-practices) for deeper guidance on real-task grounding, context economy, progressive disclosure, calibrated control, reusable scripts, and validation loops. + +## Descriptions + +Treat the frontmatter `description` as the activation contract: + +- use imperative phrasing; +- describe user intent and trigger contexts, not internal mechanics; +- include realistic positive contexts and precise near-miss boundaries; +- remain concise and within the specification's 1,024-character limit; +- test triggering with realistic should-trigger and should-not-trigger queries; +- run queries repeatedly because activation is nondeterministic; +- keep a fixed train/validation split while iterating to avoid overfitting. + +See [Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) for query design, repeated trigger testing, train/validation splits, and the optimization loop. + +## Evaluation + +1. Start with a small varied set of realistic prompts, expected outcomes, and required fixtures. +2. Run each case in a clean context with the candidate skill and a baseline: no skill for a new capability, or the original/previous skill for an update. +3. Run independent paired executors concurrently when resources allow. Do the same for independent deterministic grading. Do not let configurations share mutable state. +4. Add objective assertions after inspecting initial outputs. Use scripts for mechanical checks and concrete evidence for every pass. +5. Capture timing and token/cost data. Aggregate quality and performance deltas; inspect non-discriminating, always-failing, and high-variance assertions. +6. Generate the standard human-review artifact. Review qualitative output and benchmark data before sign-off. +7. Revise, rerun, and compare until the skill improves without overfitting. + +See [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills) for workspace structure, paired runs, assertions, grading, aggregation, analysis, and human review. From 9d20a27c60e906914e47b16c961e156e58e91953 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Thu, 30 Jul 2026 18:44:14 +0200 Subject: [PATCH 2/7] =?UTF-8?q?=F0=9F=A7=AA=20add=20validators=20for=20age?= =?UTF-8?q?nt-smith=20skill=20updates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added validation rules to verify skill-authoring reference exists and contains required guidance on concise communication, parallelism assessment, progressive disclosure, and skill lifecycle. Expanded evals to test bounded-concurrency scenarios for independent endpoint retrieval. --- scripts/validate-skill-templates.ps1 | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index 0500295..9776da0 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -1164,17 +1164,27 @@ Add-ValidationResult -Results $results -Name 'dotnet-benchmark enforces valid, p Add-ValidationResult -Results $results -Name 'Agent Smith protects informational and multi-target EditorConfig remediation' -Action { $skill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/agent-smith/SKILL.md' -GitRef $Ref $reference = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/agent-smith/references/dotnet-editorconfig-conformance.md' -GitRef $Ref + $skillAuthoring = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/agent-smith/references/skill-authoring.md' -GitRef $Ref $evals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/agent-smith/evals/evals.json' -GitRef $Ref $repair = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/agent-smith/scripts/repair-roslyn-multiproject-artifacts.ps1' -GitRef $Ref $repairTests = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/agent-smith/scripts/test-repair-roslyn-multiproject-artifacts.ps1' -GitRef $Ref Assert-Contains -Name 'agent-smith/SKILL.md' -Content $skill -Needle 'every discovery, investigation, retry, and final `dotnet format` command must include both `--severity info` and `--verify-no-changes`' Assert-Contains -Name 'agent-smith/SKILL.md' -Content $skill -Needle 'scripts/repair-roslyn-multiproject-artifacts.ps1' + Assert-Contains -Name 'agent-smith/SKILL.md' -Content $skill -Needle 'Always analyze the task graph for safe parallelism and concurrency.' + Assert-Contains -Name 'agent-smith/SKILL.md' -Content $skill -Needle '**Be concise. Sacrifice grammar for the sake of concision.**' + Assert-Contains -Name 'skill-authoring.md' -Content $skillAuthoring -Needle 'Batch independent retrieval through one multi-call request where the tool supports it.' + Assert-Contains -Name 'skill-authoring.md' -Content $skillAuthoring -Needle 'Choose C# and .NET by default for non-trivial reusable scripts' + Assert-Contains -Name 'skill-authoring.md' -Content $skillAuthoring -Needle '## Required authoring feedback' + Assert-Contains -Name 'skill-authoring.md' -Content $skillAuthoring -Needle 'Microsoft''s official .NET support policy' + Assert-Contains -Name 'skill-authoring.md' -Content $skillAuthoring -Needle 'Optimizing skill descriptions' + Assert-Contains -Name 'skill-authoring.md' -Content $skillAuthoring -Needle 'Evaluating skill output quality' Assert-Contains -Name 'dotnet-editorconfig-conformance.md' -Content $reference -Needle 'dotnet format style ""' Assert-Contains -Name 'dotnet-editorconfig-conformance.md' -Content $reference -Needle '`dotnet format` defaults to severity `warn`' Assert-Contains -Name 'dotnet-editorconfig-conformance.md' -Content $reference -Needle 'Directory application is all-or-nothing at preflight' Assert-Contains -Name 'dotnet-editorconfig-conformance.md' -Content $reference -Needle "git grep -n -F 'Unmerged change from project'" Assert-Contains -Name 'agent-smith/evals/evals.json' -Content $evals -Needle 'finish fixing all IDE0161 findings in MultiTargeted.sln' + Assert-Contains -Name 'agent-smith/evals/evals.json' -Content $evals -Needle 'fetches twelve independent service endpoints sequentially' Assert-Contains -Name 'repair-roslyn-multiproject-artifacts.ps1' -Content $repair -Needle 'function Test-LinePrefix' Assert-Contains -Name 'repair-roslyn-multiproject-artifacts.ps1' -Content $repair -Needle "pattern = 'whole-document-namespace-conversion'" Assert-Contains -Name 'repair-roslyn-multiproject-artifacts.ps1' -Content $repair -Needle "pattern = 'unrecognized'" From e3af10ece9beb2f5d740441bb004bae635dab92d Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Thu, 30 Jul 2026 18:44:36 +0200 Subject: [PATCH 3/7] =?UTF-8?q?=F0=9F=92=AC=20update=20agent-smith=20descr?= =?UTF-8?q?iption=20in=20readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated agent-smith skill summary to document new skill-authoring capabilities, concise-reporting guidelines, and bounded-concurrency assessment for independent operations. Added guidance on progressive disclosure pattern, faster skill workflows, and Agent Skills lifecycle for real-task grounding and baseline evaluation. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d2b008d..82e681a 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill agent-smith | [dotnet-change-impact](skills/dotnet-change-impact/SKILL.md) | Classify .NET library or NuGet package changes and recommend the correct release bump — `Major`, `Minor`, or `Patch` — for both Semantic Versioning (`MAJOR.MINOR.PATCH`) and .NET assembly/file versioning (`Major.Minor.Build.Revision`), grounded in Microsoft's official .NET compatibility rules. Uses the current Git branch by default when no explicit change details or compare range are provided, resolving it against the upstream/default base branch with local read-only git state. Always returns structured behavioral/binary/source/design-time/backwards compatibility reasoning with the recommendation, even when the bump is clear. | | [dotnet-docfx-digest](skills/dotnet-docfx-digest/SKILL.md) | Create and maintain developer-friendly DocFX documentation for .NET public APIs, including repo-wide no-input audits that inspect source, tests, DocFX config, DocFX `build.content` and `build.overwrite` Markdown inputs, namespace pages, and availability includes before asking for clarification, while treating bare direct skill invocations as autonomous repo-wide runs rather than human-driven checkpoint sessions. Enforces the workflow with two bundled .NET 10 file-based scripts resolved from the loaded skill directory, falling back to the repo-managed source path only when present: `scripts/agents.cs` writes an idempotent, marker-bounded DocFX maintenance block into the repository `AGENTS.md`; `scripts/docfx.cs` is **fast and build-free by default** — it validates Markdown, prose, DocFX overwrite layout, namespace overview pages, `Extension Members` tables, decorated receiver signatures such as `IDecorator`, generic method displays such as `As`, purpose-first summaries, and required per-type/extension examples without invoking `dotnet`, `msbuild`, `docfx`, or `gh`, discovering the public API from existing DocFX YAML metadata or a conservative source scan and ending every run with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary plus per-phase timings. Compilation and network access are strictly opt-in: `--validate-samples` compiles each C# sample in an isolated project while batching all sample projects into one temporary `.slnx` graph build with bounded MSBuild parallelism and scoped references, `--build-api-model` (alias `--strict-api-discovery`) does reflection-backed discovery from compiled metadata via `MetadataLoadContext` through a single scoped `.slnx` graph build, `--verify-docfx-build` runs the DocFX CLI in a temp copy, and `--search-examples` runs `gh` code search. Final verification adapts to available processors and memory, overlaps isolated DocFX work on high-capacity machines, uses a 30-minute child timeout, and emits 10-second `stderr` heartbeats with active phase, workload, runner count, PID, elapsed time, last-output age, and current child output while preserving machine-readable JSON on `stdout`. Honors a single DocFX metadata `TargetFramework` when `--framework` is omitted, collapses C# 14 extension-block compiler containers such as `$...` back to the authored outer static class in both fast DocFX-YAML discovery and build-backed reflection discovery, validates namespace fly-ins that explain the problem solved/when to use/where to start plus example fly-ins before every C# fence, the Codebelt namespace-and-type-folder overwrite layout (`.docfx/api/namespaces/**/*.md` and `.docfx/api/types/**/*.md` under `build.overwrite` only), keeps `--changed-only` validation scoped to affected docs and APIs while still including brand-new untracked overwrite Markdown, uses the root Codebelt `.snk` when present and falls back to `-p:SkipSignAssembly=true` for keyless strong-name build verification, drains child stdout and stderr concurrently to avoid verbose-build deadlocks, writes deterministic `--assessment-queue` Markdown work queues for noisy audits, preserves working URL references unless a verified HTTP 404 justifies removal, treats unexpected new repo-root or DocFX-workspace files that are not known `dotnet-docfx-digest` deliverables as blocking cleanup diagnostics, keeps assessment/manifests/captured output/helper scripts in temp or session storage instead of the target repository, requires a namespace-first pass across the active queue before net-new type/example authoring during full audits, keeps deeper `EXTENSION_METHOD_MISSING` and `EXTENSION_METHOD_SIGNATURE_MISSING` follow-on diagnostics in that same namespace-layer table-repair phase when they appear after `EXTENSION_SECTION_MISSING` drops, preserves existing BOM and line-ending state while flagging actual mojibake instead of creating encoding-only diffs, and leaves generated DocFX YAML metadata untouched unless `--clean-generated-metadata` is explicitly requested (which runs only after the API model is built, never deleting metadata the run relied on). Documents public API only, uses bundled reference docs for overwrite rules, workflow details, and script behavior, keeps authored API overwrite Markdown under `.docfx/api/namespaces/` and `.docfx/api/types/`, moves legacy authored `.docfx/api/*.md` overwrite files there instead of widening the glob to `api/**/*.md`, teaches namespace and API prose to orient newcomers around purpose instead of inventorying contents, prefers inline or small sibling-batch prose repairs over slow per-page worker fan-out, makes examples start from package-ID usage evidence before type/member-only searches and requires each example to introduce the consumer task before the code, allows multi-type Microsoft Learn-style scenario samples when they better explain the consumer workflow, keeps extension-method examples on readable declaring-class type pages under `.docfx/api/types/` instead of synthetic method-UID filenames or namespace pages that mix extra `uid:` / `example:` blocks into the overview, flags weak skip-compile reasons, requires deterministic `.docfx/skip-compile-allowlist.json` entries for any pre-existing approved skip waivers, treats newly introduced or unallowlisted skip markers as fail-level diagnostics that do not suppress compilation, establishes reflection-backed packets with `--build-api-model --project-manifest` before full-run authoring, forces mid-audit continuations to name that manifest or the sequential assessment/namespace-first fallback explicitly, requires those continuations to restate the fast `docfx.cs --json` rerun cadence, the exact final `docfx.cs --build-api-model --validate-samples --verify-docfx-build --json` gate, and the clean JSON completion contract instead of generic “verify later” prose, treats batch size only as rerun cadence rather than permission to stop, runs a completion repair loop that treats every diagnostic as active work regardless of age or volume, treats newly surfaced follow-on diagnostics as the next repair queue instead of a stop point, reruns packet discovery with `--build-api-model --project-manifest` when fast source-scan packets are unnamed or zero-project, falls back to sequential namespace-first or assessment work queue order when packet discovery is still unusable, treats `EXAMPLE_MISSING`, `EXAMPLE_LEAD_MISSING`, `EXAMPLE_ADVANCED_LEAD_MISSING`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, `SAMPLE_STRUCTURE_INVALID`, `FAIL_NEW_SKIP_MARKER_INTRODUCED`, `SAMPLE_SKIP_NOT_ALLOWLISTED`, and `INTERIM_ARTIFACT_IN_WORKTREE` queues as core work rather than checkpoints or quality backlog, drives large example and lead queues through a concrete fast-path micro-loop (next item or next 3-5 items → rerun → continue), suppresses progress-table/checkpoint output until the completion contract is clean or a real external blocker is reported, treats premature completion-shaped handoffs as execution-protocol failures while the queue is still dirty, reserves the final `--build-api-model --validate-samples --verify-docfx-build` verification for the real end of the queue, exposes `summary.fullVerificationRan`, `summary.canClaimCompletion`, `summary.remainingWorkItems`, `summary.remainingDiagnosticsByCode`, `summary.newlyIntroducedSkipMarkers`, and `summary.interimArtifacts` as machine-readable final gates, reruns the fast `docfx.cs --json` after edits until the queue is empty, then runs the build-backed verification before completion, preserves manual edits and authored Markdown during cleanup, skips recursive generated-output cleanup when a target directory contains documentation or source files, and returns deterministic exit codes plus `--json` reports (including process counts, phase timings, warning counts, and skip-marker accounting) so CI can gate on real failures instead of AI claims. | | [dotnet-benchmark](skills/dotnet-benchmark/SKILL.md) | Discovers, prioritizes, and authors trustworthy BenchmarkDotNet experiments for a .NET type following codebelt conventions and using the `Codebelt.Extensions.BenchmarkDotNet.Console` runner. It inspects implementation code, call sites, tests, existing benchmarks, and available profiles instead of benchmarking every public member; ranks likely high-impact operations; selects representative typical, boundary, scaling, and adverse cases; and rejects external-I/O or service-level questions that need profiling, macrobenchmarks, or load tests. It creates fair current-versus-candidate comparisons only when observable work is equivalent, uses baseline-free single-operation characterization when no honest comparator exists, prevents unrelated construction/formatting/equality/hash ratios, requires exact per-case correctness oracles plus a semantic preflight for truthful workload labels, hard-gates interpretation on a complete valid BenchmarkDotNet summary, preserves workload invariants such as selectivity and hit/miss ratios as sizes scale, distinguishes deferred pipeline creation from terminal/materialization work, and performs Release build, discovery listing, and dry execution before any explicit full run. Explicit `yolo` mode auto-accepts routine repo-derived defaults and the proposed plan, then proceeds through build/list/dry validation without confirmation churn; only a separate explicit human instruction can start a full performance run. Its runner preflight recognizes the standard Slim/runtime setup and explains when `SkipBenchmarksWithReports = true` plus a matching `reports/tuning/` artifact deliberately filters a benchmark, preventing needless class renames, disassembly, or tool thrash; after the first valid full result it stops unless deeper diagnostics could change a real engineering decision. Harness setup remains adaptive: it detects `.slnx`/`.sln`, CPM, existing `tuning/` projects, and a reusable `tooling/` runner, onboards only missing pieces, resolves package versions dynamically, and keeps the benchmark class in the SUT namespace. | -| [agent-smith](skills/agent-smith/SKILL.md) | Apply a rigorous, consistent, evidence-driven software-craftsmanship standard across a whole engineering task. Invoke explicitly as `/agent-smith ` or let it auto-trigger for design, architecture, implementation, refactoring, code review, public API review, compatibility and Semantic Versioning analysis, testing, benchmarking, performance, documentation, security and DevSecOps, CI/CD, delivery, repository governance, and engineering assessment. Its optional .NET EditorConfig conformance mode handles targeted IDE/CA diagnostic remediation and full informational-or-higher `dotnet format` conformance without treating a clean build as proof of policy compliance: user-defined diagnostic IDs remain task-supplied data; target, path, and severity scope remains authoritative; informational workflows explicitly preserve `--severity info` because the formatter defaults to `warn`; targeted IDE and analyzer checks use category-specific formatter subcommands; every formatter invocation is read-only via `--verify-no-changes`; `--no-restore` is never treated as a conformance fallback; fixes are deliberate source edits; repeated multi-target findings are de-duplicated by physical file, diagnostic, and span; and the bundled `repair-roslyn-multiproject-artifacts.ps1` detects conflict artifacts independently of diagnostic ID, preflights directory repairs without partial writes, repairs only proven structural patterns, and refuses unrecognized shapes. Completion requires the same scoped formatter gate plus an artifact scan before affected builds and relevant tests. Technology-neutral work remains unaffected. Performs the requested work (not just a review), loads only relevant `references/`, respects repository conventions, scales process depth without lowering the standard, and reports evidence and risk honestly. Governing principle: consistency is key. | +| [agent-smith](skills/agent-smith/SKILL.md) | Apply a rigorous, consistent, evidence-driven software-craftsmanship standard across a whole engineering task. Invoke explicitly as `/agent-smith ` or let it auto-trigger for design, architecture, implementation, refactoring, code review, public API review, compatibility and Semantic Versioning analysis, testing, benchmarking, performance, skill authoring, documentation, security and DevSecOps, CI/CD, delivery, repository governance, and engineering assessment. Skill-authoring mode grounds instructions in real execution, requires an explicit bounded-concurrency assessment so independent data retrieval and eval work do not remain sequential by habit, favors reusable C#/.NET scripts and validators against the dynamically resolved latest supported LTS when local constraints do not decide, and follows the Agent Skills guidance for progressive disclosure, description optimization, candidate-versus-baseline evaluation, aggregation, and human review. Its optional .NET EditorConfig conformance mode handles targeted IDE/CA diagnostic remediation and full informational-or-higher `dotnet format` conformance without treating a clean build as proof of policy compliance: user-defined diagnostic IDs remain task-supplied data; target, path, and severity scope remains authoritative; informational workflows explicitly preserve `--severity info` because the formatter defaults to `warn`; targeted IDE and analyzer checks use category-specific formatter subcommands; every formatter invocation is read-only via `--verify-no-changes`; `--no-restore` is never treated as a conformance fallback; fixes are deliberate source edits; repeated multi-target findings are de-duplicated by physical file, diagnostic, and span; and the bundled `repair-roslyn-multiproject-artifacts.ps1` detects conflict artifacts independently of diagnostic ID, preflights directory repairs without partial writes, repairs only proven structural patterns, and refuses unrecognized shapes. Completion requires the same scoped formatter gate plus an artifact scan before affected builds and relevant tests. Technology-neutral work remains unaffected. Performs the requested work (not just a review), loads only relevant `references/`, respects repository conventions, scales process depth without lowering the standard, and reports evidence and risk honestly in concise feedback that may sacrifice grammar but never required evidence. Governing principle: consistency is key. | ### Copyable Install Commands @@ -634,16 +634,18 @@ Setting up a benchmark "properly" is only half the problem. A benchmark can comp - **Report-aware runner preflight** — inspects the canonical `BenchmarkWorkspaceOptions.Slim` runtime jobs, `SkipBenchmarksWithReports`, and matching `reports/tuning/` artifacts before touching benchmark code, so an intentional existing-report skip is explained instead of triggering disassembly, renaming, or speculative rewrites ### Why agent-smith? -**agent-smith** applies one coherent engineering standard — *consistency is key* — across a whole task instead of bolting a review onto the end. Invoke it explicitly as `/agent-smith `; it also auto-triggers for engineering work such as architecture, implementation, code review, public API and compatibility analysis, testing, performance, security and DevSecOps, CI/CD, delivery, and governance. +**agent-smith** applies one coherent engineering standard — *consistency is key* — across a whole task instead of bolting a review onto the end. Invoke it explicitly as `/agent-smith `; it also auto-triggers for engineering work such as architecture, implementation, code review, public API and compatibility analysis, testing, performance, skill authoring, security and DevSecOps, CI/CD, delivery, and governance. - **Performs the work, not just advice** — it discovers, designs, implements, tests, documents, validates, and reports to the standard, rather than implementing normally and reviewing afterward. - **Technology-neutral core** — .NET, Git, GitHub, CI/CD, REST, and software-supply-chain guidance load only when the task calls for them, and are never imposed on non-.NET work. - **Progressive disclosure** — `SKILL.md` stays focused on posture, workflow, and mode routing; deep guidance lives in `references/` and loads only for the selected modes. +- **Faster skill workflows** — skill authoring always maps independent retrieval, execution, validation, and grading for batching or bounded concurrency, while preserving required ordering, rate limits, deterministic results, and failure attribution. Reusable scripts and validators favor C#/.NET with a dynamically resolved supported LTS unless repository or host constraints justify another choice. +- **Agent Skills lifecycle** — skill changes follow the linked Agent Skills guidance for real-task grounding, concise intent-based descriptions, realistic trigger tests, clean-context candidate-versus-baseline evals, objective grading, timing, aggregation, and human review. - **Evidence over confidence** — never invents APIs, results, or file contents; labels conclusions (Confirmed, Assumption, Requires validation) and refuses to claim validation it did not run. - **Safe multi-target conformance** — informational workflows keep `--severity info` explicit through discovery and final verification because omission falls back to `warn`; repeated Roslyn findings are de-duplicated by physical file, diagnostic ID, and source span; source is corrected once; mutating formatter passes are forbidden; and the diagnostic-neutral Roslyn artifact tool detects every `Unmerged change from project` signature while repairing only a registered structural pattern. Its first handler retains one complete namespace-conversion document only when the partial `After` branch is an exact prefix; all unrecognized shapes fail closed. The repair-tool check and conflict-artifact scan must both be clean before builds or tests. - **Respects repository precedence** — local conventions and instructions override generic preferences; a recommended deviation must explain the current convention, why it is inadequate, and how consistency is restored. - **Scales, never lowers, the standard** — a trivial change gets proportional process with no architecture ceremony; a system design gets full boundary analysis. -- **Honest reporting** — findings carry severity, evidence, and compatibility/migration impact, and completion is gated on a real checklist rather than optimism. +- **Concise, honest reporting** — feedback may sacrifice grammar for concision, but findings retain severity, evidence, compatibility/migration impact, validation limits, blockers, and material risk. Completion remains gated on a real checklist. ## Repository structure From 22ea9614e8467586bee0613e926c521ea80ce7ca Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 31 Jul 2026 17:22:40 +0200 Subject: [PATCH 4/7] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refine=20single-catego?= =?UTF-8?q?ry=20quality=20gate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The commit workflow now requires a visible full-context audit when a multi-file change initially collapses into one category, so the plan stays explicit and the quality gate cannot be skipped by yolo or auto. --- skills/git-visual-commits/SKILL.md | 18 +++++++++++++---- skills/git-visual-commits/evals/evals.json | 23 ++++++++++++++++++++++ 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/skills/git-visual-commits/SKILL.md b/skills/git-visual-commits/SKILL.md index d4253bf..e6b0474 100644 --- a/skills/git-visual-commits/SKILL.md +++ b/skills/git-visual-commits/SKILL.md @@ -1,7 +1,7 @@ --- name: git-visual-commits description: > - Structured git commit workflow with deterministically validated emoji-first subjects and identity-aware modes: `git bot commit`, regular `git commit`, and `git our commit`. Use this skill whenever the user asks to commit changes, stage files, write a commit message, or review what should be committed. Also use it when the user says "commit this", "make a commit", "commit your changes", "commit what you just did", "what should my commit message be", "stage and commit", "git bot commit", "git our commit", or combines a commit request with "yolo" or "auto". Treat commit wording as an automatic trigger for this skill, not as a casual hint. Requires a full read through EOF before action, defaults to no prefix after the emoji, allows an emoji plus conventional-commit prefix combo only when the user explicitly asks for it, blocks subjects unless they use an approved emoji, exactly one following space, a lowercase description beginning, and at most 70 characters, and verifies the stored result after commit. + Structured git commit workflow with deterministically validated emoji-first subjects and identity-aware modes: `git bot commit`, regular `git commit`, and `git our commit`. Use it whenever the user asks to commit or stage changes, write or review a commit message, or says "commit this", "git bot commit", "git our commit", "yolo", or "auto". Treat commit wording as an automatic trigger for this skill, not as a casual hint. Require a full read through EOF, semantic grouping, an approved emoji, exactly one following space, a lowercase description beginning, at most 70 characters, and post-commit verification. Default to emoji-only subjects; allow conventional-commit prefixes only on explicit request. For multi-file changes that initially collapse to one category, require a visible full-context quality gate; single-file changes may skip it. --- # Git Visual Commits @@ -281,9 +281,19 @@ For every proposed commit, verify that all files share the same *rationale*. Pre - The **explanation for why each file changed** differs materially - One file changed because of an **operational/infrastructure decision** and another because of a **framework or API change** -When only two files changed but their rationales differ, **explicitly state that two commits are warranted** in the commit plan. Small file count does not justify bundling. - -#### Commit body guidance +When only two files changed but their rationales differ, **explicitly state that two commits are warranted** in the commit plan. Small file count does not justify bundling. + +#### Single-category context quality gate + +When more than one file is changed and your first classification puts every changed file into one semantic category or commit bucket, stop before Step 3 and run this gate. Exactly one changed file is the only fast-path exception; skip this gate for that case. + +Ask yourself explicitly: **“Did I actually read the whole `git-visual-commits` skill through EOF in this session before classifying this change?”** A metadata preview, remembered rule, or partial read is a failed answer. If the answer is no or uncertain, read `SKILL.md` from its first line through EOF and restart Step 1 and Step 2. + +Then re-check the complete `git status`, `git diff`, and applicable staged diff; enumerate every changed path; explain each path's rationale, audience, and lifecycle; and consider whether any path belongs to a different category such as documentation, configuration, tooling, validation, tests, or release communication. Re-read `references/commit-language.md` before confirming the category and emoji. + +Only keep one category after this audit if every path still has one rationale. Put a visible line in the commit plan such as `Quality gate: 3 files, one category retained; full skill read, full diff review, per-file rationale check, and alternative-category check confirmed.` If any check fails or any file has a materially different intent, split the groups and rerun the normal validation. `yolo` and `auto` do not bypass this gate. + +#### Commit body guidance Unless **no-body mode** is active, every commit includes a body explaining the *why*: diff --git a/skills/git-visual-commits/evals/evals.json b/skills/git-visual-commits/evals/evals.json index e9f1f8d..ead7cba 100644 --- a/skills/git-visual-commits/evals/evals.json +++ b/skills/git-visual-commits/evals/evals.json @@ -226,6 +226,29 @@ "Runs scripts/validate-commit-subject.ps1 before showing the corrected subject and again immediately before passing it to Git", "Does not let yolo or auto bypass the full-skill read or deterministic subject validation" ] + }, + { + "id": 21, + "prompt": "Do a git bot commit, yolo. The current diff has two changed files in the same existing skill: its SKILL.md and evals/evals.json. They may share one refactor rationale. Work through the full workflow and show the plan.", + "expected_output": "A multi-file single-category plan that pauses for the context quality gate, explicitly asks whether the whole skill was read through EOF, rechecks the full diff and each file rationale, and retains one category only if the audit confirms the shared rationale.", + "expectations": [ + "Triggers the single-category context quality gate because more than one file is being placed in one category", + "Explicitly asks whether the whole git-visual-commits skill was read through EOF before accepting the one-category result", + "Rechecks complete git state and the full diff, including an explanation for every changed path", + "Considers whether a different audience, lifecycle, or intent warrants a second category before retaining one", + "Shows the quality-gate result visibly in the commit plan", + "Does not let yolo or auto bypass the quality gate" + ] + }, + { + "id": 22, + "prompt": "Do a git bot commit, yolo. Only README.md changed for a small typo fix. Work through the workflow and show the plan.", + "expected_output": "A normal single-file commit plan that still follows the full-read, diff-review, emoji-reference, and subject-validation rules without adding the multi-file single-category quality-gate ceremony.", + "expectations": [ + "Recognizes exactly one changed file as the explicit exception and skips the single-category context quality gate", + "Still reads the whole skill through EOF and reviews the changed file before planning the commit", + "Still validates the emoji and exact subject before proceeding in yolo mode" + ] } ] } From 4f3b76ecb3dcb2157ed66e2424127db0f866fc52 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Fri, 31 Jul 2026 17:22:48 +0200 Subject: [PATCH 5/7] =?UTF-8?q?=F0=9F=93=9D=20document=20the=20quality=20g?= =?UTF-8?q?ate=20in=20the=20repo=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The template validator now checks for the new quality gate language in the skill, its evals, and the repo README so the documented contract remains enforced. --- README.md | 3 ++- scripts/validate-skill-templates.ps1 | 11 +++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 82e681a..8366599 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ 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. 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-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-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. | @@ -255,6 +255,7 @@ Commit messages are the most-read documentation in any codebase — yet they're - **Repo capability additions stay explicit** — adding a brand-new skill is grouped separately from refactoring an existing skill to support it - **Shared wording rules stay in lockstep** — the duplicated `commit-language.md` reference is kept byte-for-byte identical across both git-visual skills and checked locally plus in CI - **Semantic intent splitting** — groups commits by rationale, not just file type — config and test logic are always separate +- **Single-category context gate** — when more than one file initially appears to fit one category, the agent must visibly re-confirm the full skill read, full diff review, and per-file rationale before retaining that category; a one-file change keeps the fast path - **Same-round edits are not one commit by default** — temporal proximity never outranks semantic intent when grouping changes - **Release-adjacent work still splits cleanly** — dependency baselines, package metadata, community health docs, doc publishing fixes, and CI automation can belong in separate commits even when they land together - **Package release notes are `📦` work** — `.nuget/*/PackageReleaseNotes.txt` belongs with package/publish metadata, not with `💬` community-health communication diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index 9776da0..e74d1a0 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -1213,6 +1213,7 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces $commitLanguage = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/references/commit-language.md' -GitRef $Ref $subjectValidator = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/scripts/validate-commit-subject.ps1' -GitRef $Ref $subjectTests = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/scripts/test-commit-subject.ps1' -GitRef $Ref + $readme = Get-FileText -RepoRoot $repoRoot -RelativePath 'README.md' -GitRef $Ref Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'automatic trigger for this skill, not as a casual hint.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Full-Skill Read and Subject Lock' @@ -1267,6 +1268,12 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Documentation publishing**' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Community health/release communication**' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Temporal proximity is not a grouping signal.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '#### Single-category context quality gate' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Exactly one changed file is the only fast-path exception; skip this gate for that case.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Did I actually read the whole `git-visual-commits` skill through EOF in this session before classifying this change?' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Then re-check the complete `git status`, `git diff`, and applicable staged diff; enumerate every changed path' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Put a visible line in the commit plan such as `Quality gate:' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '`yolo` and `auto` do not bypass this gate.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '#### Release-adjacent splitting rule' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Concrete example: if one diff updates `Directory.Build.targets`, `Directory.Packages.props`, or `testenvironments.json`,' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Keep `.nuget/*/PackageReleaseNotes.txt` with the' @@ -1317,6 +1324,10 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Reads SKILL.md completely through EOF before any staging or commit command' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Rejects the proposed subject because 📋 is absent from the approved commit-language table' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Runs scripts/validate-commit-subject.ps1 before showing the corrected subject and again immediately before passing it to Git' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Triggers the single-category context quality gate because more than one file is being placed in one category' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Recognizes exactly one changed file as the explicit exception and skips the single-category context quality gate' + Assert-Contains -Name 'README.md' -Content $readme -Needle '**Single-category context gate**' + Assert-Contains -Name 'README.md' -Content $readme -Needle 'Multi-file plans that initially collapse to one category also require a visible full-context quality gate' } Add-ValidationResult -Results $results -Name 'Git visual squash summary skill stays self-contained and shares commit language rules' -Action { From b3a840cdaaf6464ef0ce56911db0f130fa88fd8a Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Sat, 1 Aug 2026 15:04:24 +0200 Subject: [PATCH 6/7] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20update=20git-visual-co?= =?UTF-8?q?mmits=20skill=20to=20clarify=20auto-approval=20triggering?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The description now clarifies that yolo and auto are auto-approval modifiers only within an explicit commit request, never as standalone triggers for unrelated work. Added two new eval cases to enforce this contract: one verifies yolo in a non-commit context does not trigger the workflow, and another checks that auto in a formatter task does not cause unwanted commits. This tightens the triggering behavior and prevents accidental misuse. --- skills/git-visual-commits/SKILL.md | 4 ++-- skills/git-visual-commits/evals/evals.json | 20 ++++++++++++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/skills/git-visual-commits/SKILL.md b/skills/git-visual-commits/SKILL.md index e6b0474..dce2270 100644 --- a/skills/git-visual-commits/SKILL.md +++ b/skills/git-visual-commits/SKILL.md @@ -1,7 +1,7 @@ --- name: git-visual-commits -description: > - Structured git commit workflow with deterministically validated emoji-first subjects and identity-aware modes: `git bot commit`, regular `git commit`, and `git our commit`. Use it whenever the user asks to commit or stage changes, write or review a commit message, or says "commit this", "git bot commit", "git our commit", "yolo", or "auto". Treat commit wording as an automatic trigger for this skill, not as a casual hint. Require a full read through EOF, semantic grouping, an approved emoji, exactly one following space, a lowercase description beginning, at most 70 characters, and post-commit verification. Default to emoji-only subjects; allow conventional-commit prefixes only on explicit request. For multi-file changes that initially collapse to one category, require a visible full-context quality gate; single-file changes may skip it. +description: > + Structured git commit workflow with deterministically validated emoji-first subjects and identity-aware modes: `git bot commit`, regular `git commit`, and `git our commit`. Use it when the user asks to commit or stage changes, write or review a commit message, or invokes one of those commit commands. Treat `yolo` and `auto` as auto-approval modifiers only within an explicit commit request, never as standalone triggers for unrelated work. Treat commit wording as an automatic trigger for this skill, not as a casual hint. Require a full read through EOF, semantic grouping, an approved emoji, exactly one following space, a lowercase description beginning, at most 70 characters, and post-commit verification. Default to emoji-only subjects; allow conventional-commit prefixes only on explicit request. For multi-file changes that initially collapse to one category, require a visible full-context quality gate; single-file changes may skip it. --- # Git Visual Commits diff --git a/skills/git-visual-commits/evals/evals.json b/skills/git-visual-commits/evals/evals.json index ead7cba..0ae48b9 100644 --- a/skills/git-visual-commits/evals/evals.json +++ b/skills/git-visual-commits/evals/evals.json @@ -249,6 +249,26 @@ "Still reads the whole skill through EOF and reviews the changed file before planning the commit", "Still validates the emoji and exact subject before proceeding in yolo mode" ] + }, + { + "id": 23, + "prompt": "Please update the validator and run its checks yolo. This is a validation task only—do not stage or commit anything.", + "expected_output": "A validator-focused response that does not enter the git commit workflow merely because the user said yolo.", + "expectations": [ + "Does not trigger git-visual-commits from standalone yolo wording in a non-commit request", + "Does not propose, stage, or execute a commit", + "Keeps the response focused on the requested validator work" + ] + }, + { + "id": 24, + "prompt": "Run the formatter in auto mode for this linting task. I am not asking you to stage or commit changes.", + "expected_output": "A linting-focused response that does not enter the git commit workflow merely because the user said auto.", + "expectations": [ + "Does not trigger git-visual-commits from standalone auto wording in a non-commit request", + "Does not propose, stage, or execute a commit", + "Keeps the response focused on the requested formatter work" + ] } ] } From da8ef16d332c7fb74f1f6b170463f0476b3e63b5 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Sat, 1 Aug 2026 15:04:50 +0200 Subject: [PATCH 7/7] =?UTF-8?q?=F0=9F=92=AC=20clarify=20auto-approval=20wo?= =?UTF-8?q?rding=20in=20readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated the auto-approval bullet point to explicitly state that yolo and auto should be used within a commit request, not as standalone modifiers. This clarification helps users understand the correct usage pattern and prevents confusion about when these keywords apply. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8366599..c38a7ea 100644 --- a/README.md +++ b/README.md @@ -245,7 +245,7 @@ Commit messages are the most-read documentation in any codebase — yet they're - **Reference-validated emoji choices** — the workflow reads the bundled `commit-language.md` skill resource before proposing commit subjects and does not treat a missing repo-root `references/` folder as the same thing as a missing skill reference - **Community health uses `💬`** — changelogs and repo-health / release-status communication are treated as human-facing messaging, not generic `📝` or `📚` docs by default - **Skill refactors map to refactor intent** — reorganizing an existing skill's wording or eval contract should land on `♻️`, not a guessed new-feature or config emoji -- **Auto-approval** — say "yolo" or "auto" to skip the review gate when you trust the agent's judgment +- **Auto-approval** — say "yolo" or "auto" within a commit request to skip the review gate when you trust the agent's judgment - **No `yolo`, no commit** — without `yolo` / `auto` or an already-enabled auto mode, the workflow must stop at the plan and wait for approval before it commits anything - **Yolo skips confirmation, not discipline** — auto-approval still requires semantic grouping, mixed-scope checks, and a visible commit plan summary before committing - **Full worktree by default** — plain `git bot commit yolo` means "commit everything currently in git status and group it correctly", not "guess a narrower slice"