From c1dfcb0c596339bc9bc1e394b4cae9615fe3ba2b Mon Sep 17 00:00:00 2001
From: Piotr Zajac <p.zajac@accenture.com>
Date: Mon, 11 May 2026 11:06:48 +0200
Subject: [PATCH] feat(ai): add AI agent skills for repository workflows

Introduces 7 reusable skill prompts following the agentskills.io open
standard, stored in .ai/skills/. Each skill encodes a recurring workflow
(task orientation, validation, attribute scaffolding, etc.) so any AI
agent can follow it consistently across sessions.

Thin wrappers in .claude/commands/ expose the skills as Claude Code
/slash-commands. AGENTS.md gains an Available Skills section that
documents all 7 skills with invocation instructions for every agent type.

Closes TASK-20.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .ai/skills/add-attribute/SKILL.md             |  77 +++++++++++
 .../references/extension-model.md             | 123 ++++++++++++++++++
 .ai/skills/create-branch-pr/SKILL.md          |  78 +++++++++++
 .../create-branch-pr/assets/pr-template.md    |  21 +++
 .ai/skills/new-test/SKILL.md                  |  86 ++++++++++++
 .ai/skills/new-test/assets/test-template.md   |  94 +++++++++++++
 .ai/skills/review-decisions/SKILL.md          |  70 ++++++++++
 .ai/skills/task-finish/SKILL.md               |  84 ++++++++++++
 .ai/skills/task-start/SKILL.md                |  69 ++++++++++
 .ai/skills/validate/SKILL.md                  |  58 +++++++++
 ...I-agent-skills-for-repository-workflows.md | 100 ++++++++++++++
 .claude/commands/add-attribute.md             |   3 +
 .claude/commands/create-branch-pr.md          |   3 +
 .claude/commands/new-test.md                  |   3 +
 .claude/commands/review-decisions.md          |   1 +
 .claude/commands/task-finish.md               |   3 +
 .claude/commands/task-start.md                |   3 +
 .claude/commands/validate.md                  |   1 +
 AGENTS.md                                     |  20 +++
 19 files changed, 897 insertions(+)
 create mode 100644 .ai/skills/add-attribute/SKILL.md
 create mode 100644 .ai/skills/add-attribute/references/extension-model.md
 create mode 100644 .ai/skills/create-branch-pr/SKILL.md
 create mode 100644 .ai/skills/create-branch-pr/assets/pr-template.md
 create mode 100644 .ai/skills/new-test/SKILL.md
 create mode 100644 .ai/skills/new-test/assets/test-template.md
 create mode 100644 .ai/skills/review-decisions/SKILL.md
 create mode 100644 .ai/skills/task-finish/SKILL.md
 create mode 100644 .ai/skills/task-start/SKILL.md
 create mode 100644 .ai/skills/validate/SKILL.md
 create mode 100644 .backlog/tasks/task-20 - Create-AI-agent-skills-for-repository-workflows.md
 create mode 100644 .claude/commands/add-attribute.md
 create mode 100644 .claude/commands/create-branch-pr.md
 create mode 100644 .claude/commands/new-test.md
 create mode 100644 .claude/commands/review-decisions.md
 create mode 100644 .claude/commands/task-finish.md
 create mode 100644 .claude/commands/task-start.md
 create mode 100644 .claude/commands/validate.md

diff --git a/.ai/skills/add-attribute/SKILL.md b/.ai/skills/add-attribute/SKILL.md
new file mode 100644
index 00000000..b81411ff
--- /dev/null
+++ b/.ai/skills/add-attribute/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: add-attribute
+description: Scaffold a new xUnit2 parameter attribute in the Core project. Use this skill when adding a new [AttributeName] that applies to all mock modules (AutoMoq, AutoFakeItEasy, AutoNSubstitute). Encodes the extension model, coding conventions, and test conventions for this repository. Invoke as: add-attribute AttributeName.
+---
+
+# add-attribute
+
+Scaffold a new parameter attribute in `Core` following all repository conventions.
+
+Parameter attributes apply to individual test method parameters and affect how AutoFixture
+generates values for them. They derive from `CustomizeAttribute` (AutoFixture.Xunit2) and
+override `GetCustomization`.
+
+See `references/extension-model.md` for an annotated full example.
+
+## Steps
+
+**1. Understand the attribute's purpose**
+
+- What constraint does it place on the generated value?
+- Does it accept constructor parameters? What are their types and valid ranges?
+- Review existing similar attributes for patterns:
+  - `[Except]` — excludes specific values
+  - `[PickFromRange(min, max)]` — constrains to a numeric range
+  - `[PickFromValues(v1, v2)]` — picks from an explicit list
+  - `[PickNegative]` — generates negative numbers only
+
+**2. Create the attribute class**
+
+Path: `src/Objectivity.AutoFixture.XUnit2.Core/Attributes/<Name>Attribute.cs`
+
+Required conventions:
+
+- `sealed class` deriving from `CustomizeAttribute` (decision-28)
+- `using` directives go **inside** the namespace block (StyleCop SA1210)
+- `global::` prefix on all external packages (AutoFixture, etc.)
+- `[AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]`
+- `parameter.NotNull(nameof(parameter))` guard in `GetCustomization` (decision-29)
+- No XML doc comments on public members (decision-27); use self-documenting names
+
+**3. Create the test class**
+
+Path: `src/Objectivity.AutoFixture.XUnit2.Core.Tests/Attributes/<Name>AttributeTests.cs`
+
+Required structure:
+
+- `[Collection("<Name>Attribute")]` — use the **subject** class name
+- `[Trait("Category", "Attributes")]`
+- BDD DisplayName on every `[Fact]` and `[Theory]` (decision-24)
+- AAA structure with mandatory `// Arrange`, `// Act`, `// Assert` comments (decision-25)
+- `[AutoMockData]` placed **above** `[Theory]`
+- No `new Fixture()` — inject `IFixture` via test method parameters
+
+Minimum test coverage:
+
+- Constructor validation (invalid arguments throw expected exceptions)
+- Property values are stored correctly
+- `GetCustomization` returns a customization that causes AutoFixture to generate
+  values satisfying the constraint
+
+**4. Update AGENTS.md**
+
+Add a row to the "Parameter Attributes (Core, apply to all modules)" table:
+
+```text
+| `[<Name>]` | <short description of what it does> |
+```
+
+**5. Run validate**
+
+Follow `.ai/skills/validate/SKILL.md` to confirm build and tests pass.
+
+## Rules
+
+- Add to `Core` only if the attribute applies to all three mock modules
+- Never add Moq/FakeItEasy/NSubstitute-specific logic to `Core`
+- Build must pass with 0 warnings before marking the task complete
diff --git a/.ai/skills/add-attribute/references/extension-model.md b/.ai/skills/add-attribute/references/extension-model.md
new file mode 100644
index 00000000..359a3f29
--- /dev/null
+++ b/.ai/skills/add-attribute/references/extension-model.md
@@ -0,0 +1,123 @@
+# Extension Model Reference — Parameter Attributes
+
+This document walks through `PickFromRangeAttribute` as a canonical example of how parameter
+attributes are implemented in this repository.
+
+## Annotated source
+
+```csharp
+namespace Objectivity.AutoFixture.XUnit2.Core.Attributes
+{
+    // ① using directives go INSIDE the namespace block (StyleCop SA1210)
+    using System;
+    using System.Reflection;
+
+    // ② global:: prefix on all external packages (decision — C# style)
+    using global::AutoFixture;
+    using global::AutoFixture.Kernel;
+    using global::AutoFixture.Xunit2;
+
+    using Objectivity.AutoFixture.XUnit2.Core.Common;
+    using Objectivity.AutoFixture.XUnit2.Core.SpecimenBuilders;
+
+    // ③ AttributeUsage restricts to Parameter; AllowMultiple = false is typical
+    [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]
+    // ④ sealed class (decision-28) — all attribute-derived types are sealed
+    // ⑤ derives from CustomizeAttribute (AutoFixture.Xunit2), not DataAttribute
+    public sealed class PickFromRangeAttribute : CustomizeAttribute
+    {
+        // Public constructor overloads for each supported numeric type
+        public PickFromRangeAttribute(int minimum, int maximum)
+            : this((object)minimum, maximum)
+        {
+        }
+
+        // ... additional overloads (uint, long, ulong, double, float) follow the same pattern
+
+        // Private canonical constructor validates the range
+        private PickFromRangeAttribute(object minimum, object maximum)
+        {
+            if (((IComparable)minimum).CompareTo((IComparable)maximum) > 0)
+            {
+                throw new ArgumentOutOfRangeException(
+                    nameof(minimum),
+                    $"Parameter {nameof(minimum)} must be lower or equal to {nameof(maximum)}.");
+            }
+
+            this.Minimum = minimum;
+            this.Maximum = maximum;
+        }
+
+        public object Minimum { get; }
+
+        public object Maximum { get; }
+
+        // ⑥ override GetCustomization — the single required method from CustomizeAttribute
+        public override ICustomization GetCustomization(ParameterInfo parameter)
+        {
+            // ⑦ parameter.NotNull(nameof(parameter)) — use NotNull() guard (decision-29)
+            //    NotNull() is an extension method from Core/Common/
+            //    It throws ArgumentNullException when parameter is null
+            return new FilteringSpecimenBuilder(
+                new RequestFactoryRelay(
+                    (type) => new RangedNumberRequest(type, this.Minimum, this.Maximum)),
+                new EqualRequestSpecification(parameter.NotNull(nameof(parameter))))
+                .ToCustomization();
+        }
+    }
+}
+```
+
+## Key points
+
+| # | Rule | Where enforced |
+| --- | --- | --- |
+| ① | `using` inside namespace | StyleCop SA1210 (build fails if violated) |
+| ② | `global::` prefix on external packages | StyleCop SA1135 / team convention |
+| ③ | `[AttributeUsage(AttributeTargets.Parameter)]` | Restricts attribute usage to parameters |
+| ④ | `sealed` | decision-28 |
+| ⑤ | Derives from `CustomizeAttribute` | AutoFixture.Xunit2 integration contract |
+| ⑦ | `NotNull()` guard | decision-29 |
+
+## SpecimenBuilders used in data-narrowing attributes
+
+| Class | Purpose |
+| --- | --- |
+| `FilteringSpecimenBuilder` | Wraps a builder and applies it only to matching requests |
+| `RequestFactoryRelay` | Creates an AutoFixture request from the parameter type |
+| `EqualRequestSpecification` | Matches requests equal to the given `ParameterInfo` |
+| `RangedNumberRequest` | Built-in AutoFixture request for a number within a range |
+
+## Minimal attribute skeleton
+
+Use this as a starting point for a new attribute:
+
+```csharp
+namespace Objectivity.AutoFixture.XUnit2.Core.Attributes
+{
+    using System;
+    using System.Reflection;
+
+    using global::AutoFixture;
+    using global::AutoFixture.Xunit2;
+
+    using Objectivity.AutoFixture.XUnit2.Core.Common;
+
+    [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]
+    public sealed class MyNewAttribute : CustomizeAttribute
+    {
+        public MyNewAttribute(/* constructor parameters */)
+        {
+            // validate and store
+        }
+
+        public override ICustomization GetCustomization(ParameterInfo parameter)
+        {
+            parameter.NotNull(nameof(parameter));
+
+            // return an ICustomization that applies the constraint
+            throw new NotImplementedException();
+        }
+    }
+}
+```
diff --git a/.ai/skills/create-branch-pr/SKILL.md b/.ai/skills/create-branch-pr/SKILL.md
new file mode 100644
index 00000000..ce3b908f
--- /dev/null
+++ b/.ai/skills/create-branch-pr/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: create-branch-pr
+description: Create a feature branch and open a pull request following repository conventions. Validates branch naming, prefills the PR description from the project template, and walks through the full PR checklist. Use when ready to publish changes. Invoke as: create-branch-pr [TASK-N].
+---
+
+# create-branch-pr
+
+Create a properly named branch and open a PR with the standard description template.
+
+See `assets/pr-template.md` for the full prefilled PR description.
+
+## Steps
+
+**1. Confirm the branch name**
+
+Format: `<type>/<kebab-description>`
+
+The type must match the Conventional Commits type of the primary commit:
+
+| Type | Use when |
+| --- | --- |
+| `feat/` | new attribute or feature |
+| `fix/` | bug fix |
+| `refactor/` | code restructuring without behaviour change |
+| `chore/` | maintenance, tooling, dependency updates |
+| `ci/` | CI/CD workflow changes |
+| `docs/` | documentation only |
+
+Examples: `feat/pick-from-list-attribute`, `fix/enumerable-allocation`, `docs/add-skills`
+
+**2. Create and push the branch**
+
+```bash
+git checkout -b <branch-name>
+git push -u origin <branch-name>
+```
+
+**3. Walk through the PR checklist**
+
+Confirm each item before opening the PR:
+
+- [ ] Commit messages follow Conventional Commits (`type(scope): description`)
+- [ ] `dotnet build src/Objectivity.AutoFixture.XUnit2.AutoMock.sln` passes with no warnings
+- [ ] `dotnet test src/Objectivity.AutoFixture.XUnit2.AutoMock.sln` passes on all framework slices
+- [ ] Code coverage is not degraded (Codecov verifies on CI)
+- [ ] Mutation score is not degraded (Stryker verifies on CI)
+- [ ] New tests follow GIVEN/WHEN/THEN naming and AAA structure
+- [ ] No new `[SuppressMessage]` without a justification comment
+- [ ] No `// TODO:` comments added — open a GitHub issue instead
+- [ ] No new dependencies incompatible with the MIT license
+
+**4. Open the PR**
+
+Use the prefilled template from `assets/pr-template.md`:
+
+```bash
+gh pr create \
+  --title "<type>(scope): <description>" \
+  --body "$(cat .ai/skills/create-branch-pr/assets/pr-template.md)"
+```
+
+In the PR body:
+
+- Replace `Closes #` with the actual GitHub issue number if applicable
+- Add a label to the PR after creation (`gh pr edit <number> --add-label "<label>"`)
+- The `@coderabbitai summary` placeholder will be filled automatically by CodeRabbit on review
+
+**5. Link the backlog task** (if a TASK-N was provided)
+
+```bash
+npx backlog task edit TASK-N --status "Done"
+```
+
+## Rules
+
+- Direct pushes to `master` are not allowed — always use a feature branch
+- All checklist items must be confirmed before opening the PR
+- The PR title must follow Conventional Commits format
diff --git a/.ai/skills/create-branch-pr/assets/pr-template.md b/.ai/skills/create-branch-pr/assets/pr-template.md
new file mode 100644
index 00000000..1d13a374
--- /dev/null
+++ b/.ai/skills/create-branch-pr/assets/pr-template.md
@@ -0,0 +1,21 @@
+# Summary
+
+<!-- Placeholder in the PR description that CodeRabbit replaces with the high-level summary. -->
+@coderabbitai summary
+
+Closes #
+
+- Please add a description of the issue this PR is addressing. Link the relevant issue if applicable.
+- Add a label to the PR.
+
+## Checklist
+
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`type(scope): description`)
+- [ ] `dotnet build src/Objectivity.AutoFixture.XUnit2.AutoMock.sln` passes with no warnings
+- [ ] `dotnet test src/Objectivity.AutoFixture.XUnit2.AutoMock.sln` passes on all framework slices
+- [ ] Code coverage remains at least at the level prior the change (verified by Codecov)
+- [ ] Mutation score remains at least at the level prior the change (verified by Stryker)
+- [ ] New tests follow the GIVEN/WHEN/THEN naming convention and AAA structure (see [AGENTS.md](../AGENTS.md))
+- [ ] No new `[SuppressMessage]` without a justification comment
+- [ ] No `// TODO:` comments added - open a GitHub issue instead
+- [ ] No new dependencies introduced that are incompatible with the MIT license (verified by FOSSA)
diff --git a/.ai/skills/new-test/SKILL.md b/.ai/skills/new-test/SKILL.md
new file mode 100644
index 00000000..6076eca6
--- /dev/null
+++ b/.ai/skills/new-test/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: new-test
+description: Write a new test class for a given subject type following repository conventions. Use when adding tests for a new or existing class. Encodes BDD naming (decision-24) and AAA structure (decision-25). Invoke as: new-test SubjectClass.
+---
+
+# new-test
+
+Scaffold a properly structured test class for a given subject.
+
+See `assets/test-template.md` for a complete scaffolded class ready to copy and fill in.
+
+## Steps
+
+**1. Name the test class and file**
+
+- File: `<SubjectClass>Tests.cs`
+- Class: `<SubjectClass>Tests`
+- Namespace: mirrors the source project namespace under `.Tests`
+  - Source: `Objectivity.AutoFixture.XUnit2.Core.Attributes`
+  - Test: `Objectivity.AutoFixture.XUnit2.Core.Tests.Attributes`
+- Location: `src/<Module>.Tests/<same-folder-path-as-source>/`
+
+**2. Apply required class attributes**
+
+```csharp
+[Collection("<SubjectClass>")]   // subject class name — NOT the test class name
+[Trait("Category", "<Area>")]    // e.g. "Attributes", "AutoData", "Core"
+public class <SubjectClass>Tests
+```
+
+**3. Name test methods using BDD convention** (decision-24)
+
+For `[Theory]` (multiple data rows, precondition varies):
+
+- DisplayName: `GIVEN <precondition> WHEN <action> THEN <outcome>`
+- Method name: `Given<Precondition>_When<Action>_Then<Outcome>`
+
+For `[Fact]` (single deterministic case):
+
+- DisplayName: `WHEN <action> THEN <outcome>`
+- Method name: `When<Action>_Then<Outcome>`
+
+Rules:
+
+- `DisplayName` is **always** set; never omit it
+- GIVEN, WHEN, THEN are written in UPPER CASE; the rest is sentence case
+- Method name uses PascalCase with underscores between the three BDD sections
+- Never use `Test` as a suffix or prefix in method names
+
+**4. Structure every test with AAA** (decision-25)
+
+```csharp
+[Fact(DisplayName = "WHEN X THEN Y")]
+public void WhenX_ThenY()
+{
+    // Arrange
+
+    // Act
+
+    // Assert
+}
+```
+
+All three comment blocks are mandatory even when a section is empty.
+
+**5. Place data-source attributes above `[Theory]`**
+
+```csharp
+[AutoMockData]
+[Theory(DisplayName = "GIVEN X WHEN Y THEN Z")]
+public void GivenX_WhenY_ThenZ(IFixture fixture) { ... }
+```
+
+The data-source attribute must appear **above** `[Theory]`, never below.
+
+**6. Inject test data via parameters**
+
+- Never use `new Fixture()` in test methods
+- Inject `IFixture` via the test method signature
+- For attribute wiring tests: use `Mock<IFixture>` and `Mock<IAutoFixtureAttributeProvider>`
+
+## Rules
+
+- Every `[Fact]` and `[Theory]` must have `DisplayName` set
+- `[Collection]` must use the **subject** class name, not the test class name
+- Data-source attributes go **above** `[Theory]`
diff --git a/.ai/skills/new-test/assets/test-template.md b/.ai/skills/new-test/assets/test-template.md
new file mode 100644
index 00000000..69d5e92b
--- /dev/null
+++ b/.ai/skills/new-test/assets/test-template.md
@@ -0,0 +1,94 @@
+# Test Class Template
+
+Copy this scaffold, replace all `<placeholder>` values, and delete any sections you do not need.
+
+```csharp
+namespace Objectivity.AutoFixture.XUnit2.<Module>.Tests.<Area>
+{
+    // using directives go INSIDE the namespace block (StyleCop SA1210)
+    using global::AutoFixture;
+    using global::AutoFixture.Xunit2;
+    using Moq;  // or FakeItEasy / NSubstitute depending on the module
+    using Xunit;
+
+    // [Collection] uses the SUBJECT class name, not the test class name
+    [Collection("<SubjectClass>")]
+    [Trait("Category", "<Area>")]  // e.g. "Attributes", "AutoData", "Core"
+    public class <SubjectClass>Tests
+    {
+        // --- Fact: single deterministic case ---
+        // DisplayName: "WHEN <action> THEN <outcome>"
+        // Method name mirrors DisplayName in PascalCase_WithUnderscores
+        [Fact(DisplayName = "WHEN <action> THEN <outcome>")]
+        public void When<Action>_Then<Outcome>()
+        {
+            // Arrange
+
+            // Act
+
+            // Assert
+        }
+
+        // --- Theory: multiple data rows, precondition varies ---
+        // Data-source attribute ABOVE [Theory], never below
+        [AutoMockData]
+        [Theory(DisplayName = "GIVEN <precondition> WHEN <action> THEN <outcome>")]
+        public void Given<Precondition>_When<Action>_Then<Outcome>(
+            IFixture fixture)
+        {
+            // Arrange
+
+            // Act
+
+            // Assert
+        }
+
+        // --- Theory with inline values ---
+        [InlineAutoMockData(42)]
+        [Theory(DisplayName = "GIVEN <precondition> WHEN <action> THEN <outcome>")]
+        public void Given<Precondition>_When<Action>_Then<Outcome>2(
+            int value,
+            IFixture fixture)
+        {
+            // Arrange
+
+            // Act
+
+            // Assert
+        }
+    }
+}
+```
+
+## Placeholder guide
+
+| Placeholder | Replace with |
+| --- | --- |
+| `<Module>` | `Core`, `AutoMoq`, `AutoFakeItEasy`, or `AutoNSubstitute` |
+| `<Area>` | `Attributes`, `AutoData`, `Common`, etc. — mirrors source folder |
+| `<SubjectClass>` | The class under test (without `Tests` suffix) |
+| `<action>` | What the code does, e.g. `constructor is invoked` |
+| `<outcome>` | What the expected result is, e.g. `properties are set` |
+| `<precondition>` | The varying condition for a Theory, e.g. `value is negative` |
+
+## Common attribute wiring test pattern
+
+Tests that verify attribute wiring use `Mock<IFixture>` and `Mock<IAutoFixtureAttributeProvider>`:
+
+```csharp
+[AutoMockData]
+[Theory(DisplayName = "GIVEN attribute WHEN applied THEN customization is registered")]
+public void GivenAttribute_WhenApplied_ThenCustomizationIsRegistered(
+    Mock<IFixture> fixtureMock,
+    Mock<IAutoFixtureAttributeProvider> providerMock)
+{
+    // Arrange
+    var sut = new MyAttribute();
+
+    // Act
+    sut.GetCustomization(/* parameter */);
+
+    // Assert
+    fixtureMock.Verify(f => f.Customize(It.IsAny<ICustomization>()), Times.Once);
+}
+```
diff --git a/.ai/skills/review-decisions/SKILL.md b/.ai/skills/review-decisions/SKILL.md
new file mode 100644
index 00000000..bee3ab4d
--- /dev/null
+++ b/.ai/skills/review-decisions/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: review-decisions
+description: Audit changed files against all 29 recorded architectural decisions. Use before raising a pull request to catch decision violations before code review. Produces a compliance table with OK, Review, or Violation status per decision.
+---
+
+# review-decisions
+
+Audit the current diff against all architectural decisions recorded in `.backlog/decisions/`.
+
+## Steps
+
+**1. List changed files**
+
+```bash
+git diff --name-only HEAD
+```
+
+**2. Read all applicable decisions**
+
+All 29 decisions are in `.backlog/decisions/`. Read each one that applies to your changed files
+(see mapping below). You do not need to read every decision for every change.
+
+**3. Apply the decision mapping**
+
+| Changed file pattern | Decisions to check |
+| --- | --- |
+| `src/Core/Attributes/*.cs` | 8, 9, 17, 26, 27, 28, 29 |
+| `src/Core/**/*.cs` (non-attribute) | 3, 7, 26, 27, 28, 29 |
+| `src/*Tests*/**/*.cs` | 24, 25, 26 |
+| `src/AutoMoq/**`, `src/AutoFakeItEasy/**`, `src/AutoNSubstitute/**` | 4, 26, 27, 28 |
+| `.github/workflows/*.yml` | 10, 14, 15, 18, 19, 20 |
+| `AGENTS.md` / `CLAUDE.md` | 22, 27 |
+| `Directory.Build.props` / `.editorconfig` | 26 |
+| `dependabot.yml` | 13 |
+| `GitVersion.yml` | 12 |
+
+**4. Check compliance**
+
+Common violations to watch for:
+
+| Decision | What to check |
+| --- | --- |
+| 24 | Test `DisplayName` missing, or not UPPER CASE GIVEN/WHEN/THEN |
+| 25 | Missing `// Arrange`, `// Act`, `// Assert` comments in any test body |
+| 26 | `[SuppressMessage]` added without a justification comment |
+| 27 | XML doc comment added where self-documenting name would suffice |
+| 28 | New `public` attribute-derived type is not `sealed` |
+| 29 | Null check uses `ArgumentNullException` or `?? throw` instead of `NotNull()` |
+
+**5. Output a compliance table**
+
+```text
+| Decision | Title (short) | Applies | Status    | Note |
+|----------|---------------|---------|-----------|------|
+| 24       | BDD naming    | Yes     | OK        |      |
+| 25       | AAA structure | Yes     | Violation | Missing // Act in FooTests.cs line 42 |
+| 28       | Sealed attrs  | Yes     | OK        |      |
+```
+
+Status values:
+
+- **OK** — change complies with the decision
+- **Review** — advisory; human judgement needed; document reasoning in the PR description
+- **Violation** — change breaks the decision; must fix before opening a PR
+
+## Rules
+
+- Violations are blocking — resolve them before opening a PR
+- "Review" items are advisory; note your reasoning in the PR description if you proceed
+- If a decision does not apply to any changed file, omit it from the table
diff --git a/.ai/skills/task-finish/SKILL.md b/.ai/skills/task-finish/SKILL.md
new file mode 100644
index 00000000..8fc089cd
--- /dev/null
+++ b/.ai/skills/task-finish/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: task-finish
+description: Finalize a backlog task after implementation. Verifies acceptance criteria, checks changed files against architectural decisions, validates test quality, suggests a Conventional Commits message, and updates the task to Done. Use before committing. Invoke as: task-finish TASK-N.
+---
+
+# task-finish
+
+Verify implementation completeness and prepare a clean commit.
+
+## Steps
+
+**1. Review acceptance criteria**
+
+```bash
+npx backlog task show TASK-N
+```
+
+Go through every AC item. If any item is not satisfied, stop and complete it before continuing.
+
+**2. Map changed files to decisions**
+
+```bash
+git diff --name-only HEAD
+```
+
+| Changed file pattern | Decisions to verify |
+| --- | --- |
+| `src/Core/Attributes/*.cs` | 8, 9, 17, 26, 27, 28, 29 |
+| `src/Core/*.cs` | 3, 26, 27, 28, 29 |
+| `src/*Tests*/*.cs` | 24, 25, 26 |
+| `src/AutoMoq/**`, `src/AutoFakeItEasy/**`, `src/AutoNSubstitute/**` | 4, 26, 27, 28 |
+| `.github/workflows/*.yml` | 10, 14, 15, 18, 19, 20 |
+| `AGENTS.md` / `CLAUDE.md` | 22, 27 |
+
+**3. Verify test quality** (if test files were added or changed)
+
+Check each new or modified test method for:
+
+- `DisplayName` is set on every `[Fact]` and `[Theory]`
+- DisplayName is UPPER CASE GIVEN/WHEN/THEN format:
+  - Theory: `GIVEN <precondition> WHEN <action> THEN <outcome>`
+  - Fact: `WHEN <action> THEN <outcome>`
+- Method name mirrors DisplayName in PascalCase_WithUnderscores
+- No `Test` suffix or prefix in method names
+- Data-source attributes (`[AutoMockData]`, `[InlineAutoMockData]`) appear **above** `[Theory]`
+- Tests have `// Arrange`, `// Act`, `// Assert` section comments
+- No `new Fixture()` usage — `IFixture` injected via test method parameters
+
+**4. Run validate**
+
+Follow `.ai/skills/validate/SKILL.md` to confirm build and tests pass.
+
+**5. Suggest a commit message**
+
+Format: `type(scope): description` (imperative, lowercase, no trailing period)
+
+- `type`: feat, fix, refactor, chore, ci, docs, test, perf
+- `scope`: optional — module or area (e.g. `core`, `automoq`, `ci`)
+
+Examples:
+
+```text
+feat(core): add PickFromList parameter attribute
+test(automoq): consolidate duplicate Facts into Theories
+docs: add Available Skills section to AGENTS.md
+```
+
+**6. Update task status**
+
+Tick all AC checkboxes in the task file, then:
+
+```bash
+npx backlog task edit TASK-N --status "Done"
+```
+
+**7. Proceed to PR**
+
+Follow `.ai/skills/create-branch-pr/SKILL.md` to open the pull request.
+
+## Rules
+
+- Do not commit until every AC is confirmed
+- Do not mark Done with any AC checkbox unticked
+- One logical change per commit; follow Conventional Commits
diff --git a/.ai/skills/task-start/SKILL.md b/.ai/skills/task-start/SKILL.md
new file mode 100644
index 00000000..b2d0adf8
--- /dev/null
+++ b/.ai/skills/task-start/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: task-start
+description: Orient around a specific backlog task before writing code. Use this skill at the start of any implementation session to load task details, identify relevant architectural decisions, and suggest a branch name. Invoke as: task-start TASK-N.
+---
+
+# task-start
+
+Load a backlog task and orient for implementation.
+
+## Steps
+
+**1. Load the task**
+
+```bash
+npx backlog task show TASK-N
+```
+
+Review: title, status, assignees, labels, dependencies, and every acceptance criterion.
+If the task has unresolved dependencies (status not Done), stop and resolve them first.
+
+**2. Search for related work**
+
+```bash
+npx backlog search "<keywords from task title>"
+```
+
+Check for duplicates or related tasks to avoid overlapping work.
+
+**3. Identify relevant decisions**
+
+Read the task description and labels, then read related decisions from `.backlog/decisions/`.
+
+Quick mapping by change area:
+
+| Change area | Key decisions to read |
+| --- | --- |
+| New Core attribute | 3, 8, 9, 17, 26, 27, 28, 29 |
+| Test changes | 24, 25, 26 |
+| CI / workflow | 10, 14, 15, 18, 19, 20, 21 |
+| Documentation | 22, 27 |
+| NuGet dependencies | 13 |
+| Versioning | 12 |
+
+**4. Suggest a branch name**
+
+Format: `<type>/<kebab-summary>`
+
+| Conventional Commits type | Use when |
+| --- | --- |
+| `feat/` | new attribute or feature |
+| `fix/` | bug fix |
+| `refactor/` | restructuring without behaviour change |
+| `chore/` | maintenance or tooling |
+| `ci/` | CI/CD workflow change |
+| `docs/` | documentation only |
+
+Example: `feat/pick-from-list-attribute`
+
+**5. Mark as In Progress**
+
+```bash
+npx backlog task edit TASK-N --status "In Progress"
+```
+
+## Rules
+
+- Never start writing code before reading all acceptance criteria in full
+- If no backlog task exists for the work, suggest creating one first (`npx backlog task create ...`)
+- Check `npx backlog task list --status "In Progress"` — avoid having two tasks In Progress simultaneously
diff --git a/.ai/skills/validate/SKILL.md b/.ai/skills/validate/SKILL.md
new file mode 100644
index 00000000..3c1e3ba6
--- /dev/null
+++ b/.ai/skills/validate/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: validate
+description: Validate code changes before committing. Runs dotnet build (zero warnings required) and dotnet test, then scans changed test files for naming and structural convention violations. Use before every commit in this repository.
+compatibility: Requires .NET SDK. Run from the repository root directory.
+---
+
+# validate
+
+Run this skill before any commit to catch build warnings, test failures, and convention
+violations early.
+
+## Steps
+
+**1. Build** — zero warnings required
+
+```bash
+dotnet build src/Objectivity.AutoFixture.XUnit2.AutoMock.sln
+```
+
+The build runs StyleCop, Roslynator, SonarAnalyzer, and xunit.analyzers with
+`TreatWarningsAsErrors=true`. Any warning is a build failure. A clean build means all
+style and correctness rules pass.
+
+**2. Test** — fast slice
+
+```bash
+dotnet test src/Objectivity.AutoFixture.XUnit2.AutoMock.sln --framework net10.0
+```
+
+For full coverage across all framework slices (net10.0, net472, net48 on Windows):
+
+```bash
+dotnet test src/Objectivity.AutoFixture.XUnit2.AutoMock.sln
+```
+
+**3. Scan changed test files for convention violations**
+
+Run `git diff --name-only HEAD` and check each modified `*Tests.cs` file:
+
+| Check | Rule |
+| --- | --- |
+| Missing DisplayName | Every `[Fact]` and `[Theory]` must have `DisplayName = "..."` |
+| Wrong DisplayName format | Theory: `GIVEN ... WHEN ... THEN ...`; Fact: `WHEN ... THEN ...` — GIVEN/WHEN/THEN in UPPER CASE |
+| Test in method name | Method name must not start or end with `Test` |
+| Wrong attribute order | `[AutoMockData]`/`[InlineAutoMockData]`/`[MemberAutoMockData]` must appear **above** `[Theory]` |
+| Direct Fixture instantiation | No `new Fixture()` — inject `IFixture` via test method parameters |
+| Missing AAA comments | Every test body must have `// Arrange`, `// Act`, `// Assert` section comments |
+
+**4. Report results**
+
+List each issue with file name and violated rule. A clean output with no issues means the
+change is ready to commit.
+
+## Pass criteria
+
+- Build exits with code 0, zero warnings
+- All tests pass
+- No convention violations in changed test files
diff --git a/.backlog/tasks/task-20 - Create-AI-agent-skills-for-repository-workflows.md b/.backlog/tasks/task-20 - Create-AI-agent-skills-for-repository-workflows.md
new file mode 100644
index 00000000..656da80b
--- /dev/null
+++ b/.backlog/tasks/task-20 - Create-AI-agent-skills-for-repository-workflows.md	
@@ -0,0 +1,100 @@
+---
+id: TASK-20
+title: Create AI agent skills for repository workflows
+status: Done
+assignee:
+  - claude
+  - piotrzajac
+created_date: '2026-05-08 21:32'
+updated_date: '2026-05-08 21:47'
+labels:
+  - agent
+  - skills
+dependencies: []
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+The repository has comprehensive conventions in AGENTS.md (29 decisions, BDD test naming, AAA
+structure, extension model) but no reusable skill prompts for AI agents. Every new session
+repeats the same orientation work. Skills encode these repeated workflows as self-contained
+prompt files, reducing per-session setup time and keeping every agent consistent.
+
+### Storage layout
+
+```text
+.ai/skills/
+├── task-start/
+│   └── SKILL.md
+├── task-finish/
+│   └── SKILL.md
+├── validate/
+│   └── SKILL.md
+├── add-attribute/
+│   ├── SKILL.md
+│   └── references/
+│       └── extension-model.md
+├── review-decisions/
+│   └── SKILL.md
+├── new-test/
+│   ├── SKILL.md
+│   └── assets/
+│       └── test-template.md
+└── create-branch-pr/
+    ├── SKILL.md
+    └── assets/
+        └── pr-template.md
+```
+
+Each `SKILL.md` follows the [agentskills.io open standard](https://agentskills.io/home) with
+required `name` and `description` frontmatter and step-by-step Markdown body (<500 lines).
+
+Claude Code thin wrappers in `.claude/commands/*.md` point to the canonical `.ai/skills/`
+files to avoid duplication while providing native `/slash-command` support.
+
+### Skill definitions
+
+**`task-start` (arg: TASK-N)** — Before writing code: load task and ACs from backlog, surface
+related decisions, suggest branch name, remind to mark In Progress.
+
+**`task-finish` (arg: TASK-N)** — After implementation: confirm all ACs, map changed files
+to decisions, verify test naming (decision-24) and structure (decision-25), suggest
+Conventional Commits message, update task to Done, show PR checklist.
+
+**`validate` (no arg)** — Pre-commit: `dotnet build` (0 warnings), `dotnet test --framework
+net10.0`, scan test files for missing `DisplayName`, `Test` suffix/prefix, wrong attribute
+ordering.
+
+**`add-attribute` (arg: AttributeName)** — Scaffold a new Core parameter attribute: sealed
+class (decision-28), `NotNull()` guard (decision-29), StyleCop-compliant usings, matching
+test class, AGENTS.md table update.
+
+**`review-decisions` (no arg)** — Audit `git diff HEAD` against all 29 decisions; output
+compliance table with OK / Review / Violation per decision.
+
+**`new-test` (arg: SubjectClass)** — Guide writing a test: BDD naming template
+(decision-24), AAA scaffold (decision-25), `[Collection]`/`[Trait]` boilerplate,
+attribute-ordering reminder, no `new Fixture()`.
+
+**`create-branch-pr` (arg: TASK-N optional)** — Guide branch creation and PR opening:
+validate branch name convention, prefill PR description from `.github/pull_request_template.md`
+(with `@coderabbitai summary` and `Closes #`), walk through full checklist, suggest
+`gh pr create` command.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `.ai/skills/` directory exists with 7 skill subdirectories
+- [x] #2 Each skill directory contains a valid `SKILL.md` with `name` and `description` frontmatter following agentskills.io spec
+- [x] #3 `task-start` skill loads backlog task, surfaces related decisions, suggests branch name
+- [x] #4 `task-finish` skill confirms ACs, checks decisions, suggests commit message, updates task status
+- [x] #5 `validate` skill runs dotnet build and test and scans for test convention violations
+- [x] #6 `add-attribute` skill scaffolds sealed attribute class and test following decisions 26-29
+- [x] #7 `review-decisions` skill maps changed files to decisions and outputs a compliance table
+- [x] #8 `new-test` skill scaffolds BDD/AAA test following decisions 24-25
+- [x] #9 `create-branch-pr` skill guides branch and PR creation using the `.github/pull_request_template.md` checklist
+- [x] #10 `.claude/commands/` contains 7 thin wrapper `.md` files pointing to corresponding `.ai/skills/` files
+- [x] #11 AGENTS.md has an "Available Skills" section listing all 7 skills with invocation instructions for Claude Code and other agents
+<!-- AC:END -->
diff --git a/.claude/commands/add-attribute.md b/.claude/commands/add-attribute.md
new file mode 100644
index 00000000..e9314f91
--- /dev/null
+++ b/.claude/commands/add-attribute.md
@@ -0,0 +1,3 @@
+Read and follow `.ai/skills/add-attribute/SKILL.md` to scaffold a new parameter attribute.
+
+Attribute name: $ARGUMENTS
diff --git a/.claude/commands/create-branch-pr.md b/.claude/commands/create-branch-pr.md
new file mode 100644
index 00000000..98f82b4d
--- /dev/null
+++ b/.claude/commands/create-branch-pr.md
@@ -0,0 +1,3 @@
+Read and follow `.ai/skills/create-branch-pr/SKILL.md` to create a feature branch and open a pull request.
+
+Task ID (optional): $ARGUMENTS
diff --git a/.claude/commands/new-test.md b/.claude/commands/new-test.md
new file mode 100644
index 00000000..64009b91
--- /dev/null
+++ b/.claude/commands/new-test.md
@@ -0,0 +1,3 @@
+Read and follow `.ai/skills/new-test/SKILL.md` to scaffold a new test class following repository conventions.
+
+Subject class: $ARGUMENTS
diff --git a/.claude/commands/review-decisions.md b/.claude/commands/review-decisions.md
new file mode 100644
index 00000000..bda2d035
--- /dev/null
+++ b/.claude/commands/review-decisions.md
@@ -0,0 +1 @@
+Read and follow `.ai/skills/review-decisions/SKILL.md` to audit the current diff against all architectural decisions.
diff --git a/.claude/commands/task-finish.md b/.claude/commands/task-finish.md
new file mode 100644
index 00000000..fee1c0e8
--- /dev/null
+++ b/.claude/commands/task-finish.md
@@ -0,0 +1,3 @@
+Read and follow `.ai/skills/task-finish/SKILL.md` to finalize the task and prepare a commit.
+
+Task ID: $ARGUMENTS
diff --git a/.claude/commands/task-start.md b/.claude/commands/task-start.md
new file mode 100644
index 00000000..0d21b950
--- /dev/null
+++ b/.claude/commands/task-start.md
@@ -0,0 +1,3 @@
+Read and follow `.ai/skills/task-start/SKILL.md` to orient around the backlog task.
+
+Task ID: $ARGUMENTS
diff --git a/.claude/commands/validate.md b/.claude/commands/validate.md
new file mode 100644
index 00000000..0d48106c
--- /dev/null
+++ b/.claude/commands/validate.md
@@ -0,0 +1 @@
+Read and follow `.ai/skills/validate/SKILL.md` to validate the current changes before committing.
diff --git a/AGENTS.md b/AGENTS.md
index 6a843b17..3dd70a5c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -317,6 +317,26 @@ Publishing to nuget.org and GitHub Packages happens **only on pushes to master**
 
 ---
 
+## Available Skills
+
+All skills live in `.ai/skills/`. Each skill directory contains a `SKILL.md` with step-by-step
+instructions following the [agentskills.io open standard](https://agentskills.io/home).
+
+- **Claude Code**: invoke as `/skill-name [argument]` (e.g. `/task-start TASK-20`)
+- **Other agents**: ask your agent to read and follow `.ai/skills/<name>/SKILL.md`
+
+| Skill | Argument | Use when |
+| --- | --- | --- |
+| `task-start` | `TASK-N` | Beginning work on a backlog task |
+| `task-finish` | `TASK-N` | Finalizing implementation before committing |
+| `validate` | none | Before every commit |
+| `add-attribute` | `AttributeName` | Creating a new Core parameter attribute |
+| `review-decisions` | none | Before raising a PR |
+| `new-test` | `SubjectClass` | Writing a new test class |
+| `create-branch-pr` | `TASK-N` (optional) | Opening a PR for a feature branch |
+
+---
+
 ## AI Agent Working Rules
 
 These rules apply to all AI coding assistants working in this repository.