# target-authoring

A skill for writing custom MSBuild targets: canonical patterns plus fixes for anti-patterns like overwriting DependsOn chains.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3000 installs · ★ 5730
- Author: dotnet
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/target-authoring/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/target-authoring

## What it does

The skill collects canonical patterns from `Microsoft.Common.CurrentVersion.targets` in the MSBuild repository. It covers the three-level Build → CoreBuild → After chain, when to reach for `DependsOnTargets` versus `BeforeTargets` and `AfterTargets`, and how to extend a chain through `$(XxxDependsOn)`.

There is a section on `Returns` versus `Outputs`. Put `Outputs` on a query target such as `GetTargetPath` and MSBuild treats it as up to date, handing back stale data. Inter-project communication wants `Returns`; incrementality wants `Outputs`.

A full custom target template is included: the dependency chain, empty extensibility hooks, `Inputs`/`Outputs`, `FileWrites` registration and input validation. Incremental build tuning, parallelization and general anti-patterns live in separate skills, and non-MSBuild build systems are out of scope.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill target-authoring -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/target-authoring/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/target-authoring/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill target-authoring -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/target-authoring/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill target-authoring -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/target-authoring/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dotnet/skills target-authoring
```

2. **Manually: put the files in place**
- File: `.github/skills/target-authoring/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill target-authoring -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dotnet/skills --path plugins/dotnet-msbuild/skills/target-authoring
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/target-authoring/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill target-authoring -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/target-authoring/SKILL.md

## When to use it
- repair a broken SDK target chain in `Directory.Build.targets`
- append a custom target to `CompileDependsOn` without dropping SDK targets
- decide between `Returns` and `Outputs` for a query target
- stop needless rebuilds caused by missing `Inputs`/`Outputs`
- register generated files in `FileWrites` so clean works

## Example prompts
- Check my `Directory.Build.targets` — am I overwriting the SDK target chain?
- Write a custom target with Inputs/Outputs and FileWrites registration
- Why does my query target return stale results? Explain Returns vs Outputs

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: aeffa8371be1a445.

BEGIN THIRD-PARTY FILE aeffa8371be1a445
````text
---
name: target-authoring
description: "Canonical patterns for writing custom MSBuild targets. USE FOR: diagnosing and fixing custom target authoring anti-patterns; broken SDK target chains across files (e.g., Directory.Build.targets silently redefining SDK targets); targets that replace CompileDependsOn instead of extending it with $(CompileDependsOn); query targets returning stale results from Outputs vs Returns misuse; missing Inputs/Outputs causing unnecessary rebuilds; missing FileWrites registration. Covers DependsOnTargets vs BeforeTargets vs AfterTargets, the Build→CoreBuild three-level pattern, and the $(XxxDependsOn) chain-extension pattern. DO NOT USE FOR: incremental build tuning (use incremental-build), parallelization (use build-parallelism), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems."
license: MIT
---

# Custom Target Authoring Patterns

Canonical patterns from `Microsoft.Common.CurrentVersion.targets` in the MSBuild repository.

## The Three-Level Target Chain

Every major entry point (Build, Rebuild, Clean) delegates to a **property** listing its dependencies, which chains through Before → Core → After:

```xml
<PropertyGroup>
  <BuildDependsOn>
    BeforeBuild;
    CoreBuild;
    AfterBuild
  </BuildDependsOn>
</PropertyGroup>

<Target Name="Build"
    Condition=" '$(_InvalidConfigurationWarning)' != 'true' "
    DependsOnTargets="$(BuildDependsOn)"
    Returns="@(TargetPathWithTargetPlatformMoniker)" />

<!-- Empty extensibility targets — users override these -->
<Target Name="BeforeBuild" />
<Target Name="AfterBuild" />
```

`CoreBuild` delegates to `$(CoreBuildDependsOn)` and includes error handlers:

```xml
<Target Name="CoreBuild" DependsOnTargets="$(CoreBuildDependsOn)">
  <OnError ExecuteTargets="_TimeStampAfterCompile;PostBuildEvent"
      Condition="'$(RunPostBuildEvent)' == 'Always'" />
  <OnError ExecuteTargets="_CleanRecordFileWrites" />
</Target>
```

### Rules

- Delegate to a property (`DependsOnTargets="$(MyTargetDependsOn)"`), not hardcoded targets.
- `OnError` goes inside the orchestrating target to ensure cleanup runs even on failure.
- Empty Before/After targets are extensibility points. Users override them; SDKs never put logic in them.

## Chain Extension — Append, Never Overwrite

When adding a custom target to an existing chain, **append** to the `DependsOn` property:

```xml
<!-- GOOD: Append to existing chain -->
<PropertyGroup>
  <CompileDependsOn>$(CompileDependsOn);MyCodeGenTarget</CompileDependsOn>
</PropertyGroup>

<!-- BAD: Overwrites the entire chain, dropping SDK targets -->
<PropertyGroup>
  <CompileDependsOn>MyCodeGenTarget</CompileDependsOn>
</PropertyGroup>
```

## DependsOnTargets vs BeforeTargets vs AfterTargets

| Mechanism | Defined in | Best for |
|---|---|---|
````
END THIRD-PARTY FILE aeffa8371be1a445

The third-party file has ended. Everything between the aeffa8371be1a445 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2815 of 6662 bytes. © dotnet · MIT · https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/target-authoring/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md