{
"schema": "https://ai-atoms.com/schemas/skill-v1.json",
"type": "skill",
"id": "skill/item-management",
"version": "1.0.0",
"name": "item-management",
"description": "Patterns for managing MSBuild item groups: Include/Remove/Update semantics, item metadata, batching with %(Metadata), transforms, per-item filtering, and cross-product batching pitfalls. Only activate in MSBuild/.NET build context. USE FOR: diagnosing and fixing item group anti-patterns in .csproj files, reviewing item management for correctness, fixing CS2002 duplicate file warnings from SDK globbing, fixing targets that run more times than expected due to cross-product batching, fixing Include vs Update misuse on SDK-globbed items, fixing FileWrites registration for generated file clean support, moving generated files to IntermediateOutputPath. DO NOT USE FOR: target chain architecture (use target-authoring), property patterns (use property-patterns), incrementality (use incremental-build), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.",
"system_prompt_fragment": "# MSBuild Item Management Patterns\n\nCanonical patterns for working with item groups, from `Microsoft.Common.CurrentVersion.targets`.\n\n## Include / Remove / Update — Three Operations\n\n| Operation | Purpose | When to use |\n|---|---|---|\n| `Include` | Add new items to the group | Creating items with identity + metadata |\n| `Remove` | Remove items matching a pattern | Excluding files or clearing a group |\n| `Update` | Modify metadata on existing items | Adding/changing metadata without re-adding |\n\n### Include — Add Items\n\n```xml\n\n \n true\n \n\n```\n\n### Remove — Subtract Items\n\n```xml\n\n \n \n\n \n <_CleanOrphanFileWrites Include=\"@(_CleanPriorFileWrites)\"\n Exclude=\"@(_CleanCurrentFileWrites)\" />\n\n \n <_Temporary Remove=\"@(_Temporary)\" />\n\n```\n\n### Update — Modify Existing Items\n\n```xml\n\n \n true\n Microsoft.CodeAnalysis.Collections.SR\n \n\n```\n\n`Update` does not add items — it only modifies items already in the group.\n\n## Item Batching — %(Metadata)\n\nWhen `%(Metadata)` appears in target attributes or task parameters, MSBuild **batches** execution per unique metadata value.\n\n### Target-level batching (Outputs)\n\n```xml\n\n \n\n```\n\n### Task-level batching\n\n```xml\n'$(OutDir)%(TargetPath)')\">\n\n```\n\n### Per-item filtering with Condition\n\n```xml\n\n <_ResxOutput Include=\"@(EmbeddedResource->'%(OutputResource)')\"\n Condition=\"'%(EmbeddedResource.WithCulture)' == 'false'\" />\n\n```\n\n### Batching rules\n\n- `%(Metadata)` in `Condition` or `Outputs` → target batches per unique value.\n- `%(Metadata)` in task parameters → task batches per unique value.\n- **Do not mix `%()` from different item groups** in the same expression — this causes a cross-product (see Common Pitfalls).\n\n## Item Transforms — @(Item->'expression')\n\nTransforms create new item lists by applying an expression to each item:\n\n```xml\n\n'$(OutDir)%(Filename)%(Extension)')\"/>\n\n\n'%(Filename)', ', ')\" />\n```\n\n## Exclude Pattern — Set Subtraction on Include\n\n```xml\n\n \n\n```\n\n`Exclude` only works on `Include` — it cannot be used with `Update` or `Remove`.\n\n## Conditional Item Inclusion\n\n```xml\n\n\n \n\n\n\n\n \n\n```\n\n## PrivateAssets on Tool/Analyzer Packages\n\n```xml\n\n \n \n\n```\n\n## Common Pitfalls\n\n### Cross-product batching\n\nReferencing `%(Metadata)` from two different item groups creates O(N×M) executions:\n\n```xml\n\n\n\n\n\n```\n\n### Generated files in source tree\n\nWrite to `$(IntermediateOutputPath)` (obj/), not the source directory. Source-tree generation pollutes version control and can cause duplicate compilation via globs.\n\n### Missing FileWrites\n\nEvery file created during a target must be added to `@(FileWrites)` for `dotnet clean` support.",
"applicable_domains": [
"code",
"dotnet",
"engineering"
],
"invocation": [
"/item-management"
],
"tags": [
"dotnet-msbuild",
"dotnet",
"csharp",
"microsoft"
],
"authored_by": "anthropics",
"source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/item-management/SKILL.md",
"lifecycle": "stable",
"category": "dotnet",
"provenance": {
"source": "dotnet/skills",
"source_url": "https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/skills/item-management/SKILL.md",
"author": "Microsoft / .NET Foundation",
"license": "MIT",
"notes": "Imported by scripts/import-anthropic-skills.py."
}
}