Claude Code Skill

Artisan.Orm skill for Claude Code

The Artisan.Orm repository includes a Claude Code skill that helps write, review, and debug applications using the library. It gives Claude library-specific guidance, working examples, and a map of the relevant APIs and source files.

The skill is being prepared alongside Artisan.Orm 4.1.0. Its examples describe that release's source contract, including mapper validation, string normalization, explicit read factories, caller-owned transactions, scoped caches, corrected hierarchy SQL, and explicit Ok handling in DataReply. This is not a claim that a 4.1.0 package is already published. Check the version used by your application before applying an example to an older package.

Source: the artisan-orm skill folder.

What the skill helps with

The skill provides context that is easy to miss when working from general ADO.NET knowledge alone:

Task	Guidance supplied by the skill
Repositories and stored procedures	Which callbacks configure commands, which must execute them, and how connections are owned
Mappers	Reader column order and nullability, RequiredMethod, registered versus automatic mapping, and analyzer diagnostics
Parameters and TVPs	Typed SqlParam factories, SQL types and sizes, mapped/automatic TVP overloads, UDTT column order, and normalization flags
Reads and asynchronous code	Repository/command/reader choices, dynamic and compact rows, dictionaries, multiple results, streaming, and cancellation
Bulk copy and generation	Mapped/automatic bulk inserts, buffering and transaction ownership, and review of generated C#/SQL scaffolding
Writes and object graphs	Borrowed transaction ownership, temporary IDs, key-pair correlation, explicit application order, and deadlock boundaries
DataReply	Optional status/message protocol, successful payload handling, explicit JSON settings, and application HTTP policy

For example, a mapper declaring RequiredMethod.AllMain promises CreateObject, CreateDataTable, and CreateDataRow, even if it currently has no write callers. The skill explains how to choose that contract and interpret the resulting diagnostics. A mapper intended only for entity reads normally declares RequiredMethod.CreateObject.

The graph guidance explains why OUTPUT key pairs preserve relationships independently of row order, why persisted SortOrder plus ORDER BY preserves application order, and why clustered indexes do not guarantee deadlock freedom. It distinguishes the identity-computation guarantee of INSERT ... SELECT ... ORDER BY from MERGE behavior and notes that the library supplies no automatic retry policy. See graph saving and 4.1.0 changes.

The guidance also distinguishes the three-argument mapped TVP overload from the automatic-mapping overload with an explicit column list. It records that trimToNull runs before truncation or length validation in the 4.1.0 contract.

Files included

The skill lives in the repository root under .claude/skills/artisan-orm/:

.claude/
  skills/
    artisan-orm/
      SKILL.md
      references/
        reading-and-mapping.md
        parameters-and-types.md
        writes-and-transactions.md
        execution-levels.md
        result-shapes.md
        bulk-copy.md
        code-generation.md
      evals/
        evals.json
        running-evals.md

SKILL.md defines when the skill applies and directs Claude to the relevant reference. The references hold detailed contracts and examples. The parameter reference links to the shared User model and mapper in the reading reference, so copying only SKILL.md loses required context.

evals/evals.json contains verification scenarios for skill maintainers; evals/running-evals.md defines the evaluation protocol. These are not application code and are not needed for ordinary repository tasks.

Use it in this repository or another application

In a checkout containing the skill, start Claude Code at the repository root. The project skill is available to that session. For another application, copy the entire artisan-orm skill folder into that application's .claude/skills/, preserving its files and relative paths. Installing the Artisan.ORM NuGet package does not install these skill files.

Commit the project skill when the team should share it. A personal installation at ~/.claude/skills/artisan-orm/ is also supported for local Claude Code sessions across projects. Check for an older same-named personal copy: it can take precedence over the project copy. See the official skill locations and precedence documentation.

In a consumer application, the library's source-map paths may not exist. The skill directs Claude to inspect the actual package API, application repositories, and matching documentation instead. You do not need to copy the library's source tree just to use the skill.

Keep local settings out of Git

The shared skill belongs in version control; personal Claude Code settings do not. The Artisan.Orm repository uses:

# Claude Code: share skills, keep other files local
.claude/*
!.claude/skills/

This allows the skill folder while ignoring .claude/settings.local.json and other local files directly under .claude/. If an application currently ignores the entire .claude/ directory, replace that rule with the pattern above so Git can reach the skill folder. Keep any additional project-specific ignore rules that are still needed. Ignore rules do not untrack files already committed.

Automatic and explicit use

Claude Code uses the skill's description to decide when it is relevant. The intended scope is work in a project already using Artisan.Orm, or an explicit request to adopt the library. The request does not have to name Artisan.Orm when project dependencies or existing code establish that context.

Unrelated EF Core, Dapper, plain ADO.NET, and SQL-only tasks are outside this skill's scope. The presence of C# or SQL Server alone is insufficient. Selection depends on the session and model; availability does not guarantee invocation for every relevant request. See Claude Code skill invocation.

For explicit use, enter /artisan-orm with the task at the Claude Code prompt. Example requests include:

• /artisan-orm Review this mapper against the stored procedure's SELECT columns and RequiredMethod contract.
• /artisan-orm Add a TVP parameter for this collection using the supplied UDTT definition.
• /artisan-orm Check transaction ownership and cancellation handling in this repository method.

Provide the relevant model, existing repository code, procedure or SELECT definition, and UDTT schema when applicable. These establish column order, types, nullability, result-set order, and ownership. The skill cannot infer those contracts reliably from C# property names alone.

How it complements Roslyn and tests

Component	Responsibility
Claude Code skill	Guides the assistant when generating, explaining, or reviewing code
Roslyn analyzer	Checks mapper declarations and supported calls during builds and editor analysis
Runtime mapper validation	Discovers registrations and validates required methods and delegate binding
Tests	Check actual behavior, including contracts that need real SQL results and data

The skill is documentation consumed by the assistant. It does not execute in a deployed application, register mappers, or replace the compiler analyzer. Generated code still needs review and validation against the application's actual library version and SQL schema.

The analyzer cannot verify that a SELECT returns the expected ordinal positions, that a column is never null, or that a database UDTT matches a DataTable. Keep the appropriate database tests. See compile-time mapper validation and testing your repository.

Verification scenarios

The repository includes 27 skill scenarios, with 136 assertions. They cover:

• Existing Artisan.Orm code, explicit adoption, mapper requirements, and shared TVP examples.
• String flags, result projections, transaction ownership, caches, SQL hierarchy fixes, and DataReply.
• Bulk-copy mapping and buffering, dynamic/dictionary/compact results, output/JSON/date parameters, and rowversion helpers.
• Code-generation review and choosing repository, command, or reader entry points.
• Negative selection cases for unrelated EF Core, SQL-only, plain SqlClient bulk-copy, and JSON tasks.

The six selection cases each have three independent attempts in a complete evaluation, giving 39 sessions. Counts describe the current scenario inventory; they are not a claim that every execution or the newest skill revision passes. Automatic selection and answer correctness are separate checks. Preserve earlier reports as evidence for their frozen revisions, and report any partial smoke check as partial. The tests and compiler remain authoritative for executable code.

For an activation check, use a fresh session and isolated project context without explicitly invoking the skill or supplying expected answers. Inspect actual skill invocation and loading in the execution log. A direct file read, a failed invocation, and a successful skill load are different observations. Authentication or other infrastructure failures are inconclusive, rather than successful non-selection. Record the Claude Code version and model with the results.

The TVP scenario already refers to an opened skill reference, so it primarily checks example dependencies and provides weaker evidence of unsolicited discovery. See the evaluation protocol for the maintenance workflow.

See also: SqlParam factories, Getting Started, Mappers, RequiredMethod, table parameters, and DataReply.