OpenParable
Skip to content
← Back to skills

Run Apichief

Testing & Quality
run-apichief

Run Apichief is an Agent Skill for testing & quality published in the dotnet/dotnet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Run ApiChief in the EF Core repo to emit baselines, summaries, deltas, review files, or breaking-change checks. Use when refreshing `*.baseline.json`, preparing API review artifacts, or validating API changes.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/dotnet/dotnet/blob/HEAD/src/efcore/.agents/skills/run-apichief/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/run-apichief, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Run ApiChief

Use the ApiChief tool to inspect or refresh EF Core public API baselines for projects under src/.

ApiChief can run against either a compiled assembly or a previously emitted baseline JSON file. Prefer the repo-local .dotnet SDK and the checked-in build scripts in this repo.

Commands

CommandDescriptionExtra arguments
emit baselineEmit a JSON API baseline-o <file>
emit summaryEmit a human-readable API summary-o <file>, -x
emit reviewEmit API review files-o <dir>, -n
emit deltaEmit a delta against an existing baseline, or markdown diff review files<baseline-path>, -o <file-or-dir>, --diff
check breakingFail if breaking changes exist vs. a baseline<baseline-path>

Default to emit baseline if the user only asks to "run ApiChief".

Workflow

1. Identify the target project(s)

  • Match user intent against project folders under src/.
  • Ask for clarification only if the target is ambiguous.
  • The checked-in baseline path convention in this repo is src/<ProjectName>/<ProjectName>.baseline.json.
  • If asked just to update the baselines, run EFCore.ApiBaseline.Tests tests and skip the rest of the steps below.

2. Prepare the environment

Always initialize the repo environment before building or running the tool:

.\restore.cmd
. .\activate.ps1
dotnet build .\eng\Tools\ApiChief\ApiChief.csproj --nologo --verbosity q

On Bash:

./restore.sh
. ./activate.sh
dotnet build ./eng/Tools/ApiChief/ApiChief.csproj --nologo --verbosity q

3. Ensure the target binaries exist

ApiChief operates on built assemblies. If the target project has not been built yet, build it first.

Preferred options:

# Refreshes checked-in baselines after the normal build
.\build.cmd -c Debug

# Or build a single project when working narrowly
dotnet build .\src\<ProjectName>\<ProjectName>.csproj --nologo --verbosity q

Use the highest available net* TFM under artifacts/bin/<ProjectName>/<Configuration>/ by default. Avoid netstandard* and net4* targets unless the user explicitly asks for them.

4. Locate the built ApiChief binary and target assembly

$dotnet = ".\\.dotnet\\dotnet"
$apiChiefProject = ".\\eng\\Tools\\ApiChief\\ApiChief.csproj"
$apiChief = (& $dotnet msbuild $apiChiefProject --getProperty:TargetPath -p:Configuration=Debug --nologo).Trim()

$name = "<ProjectName>"
$tfm = Get-ChildItem ".\\artifacts\\bin\\$name\\Debug" -Directory |
    Where-Object { $_.Name -match '^net\d+\.\d+$' } |
    Sort-Object { [version]($_.Name -replace '^net', '') } -Descending |
    Select-Object -First 1 -ExpandProperty Name

$assemblyName = (& $dotnet msbuild ".\\src\\$name\\$name.csproj" --getProperty:AssemblyName -p:Configuration=Debug --nologo).Trim()
if ([string]::IsNullOrWhiteSpace($assemblyName))
{
    $assemblyName = $name
}

$assemblyPath = ".\\artifacts\\bin\\$name\\Debug\\$tfm\\$assemblyName.dll"

Before running, report the selected TFM if it matters for the task.

5. Run the requested ApiChief command

# Emit a baseline
& $dotnet $apiChief $assemblyPath emit baseline -o ".\\src\\$name\\$name.baseline.json"

# Emit a summary
& $dotnet $apiChief $assemblyPath emit summary

# Emit a delta
& $dotnet $apiChief $assemblyPath emit delta ".\\src\\$name\\$name.baseline.json" -o ".\\artifacts\\tmp\\$name.delta.json"

# Check for breaking changes
& $dotnet $apiChief $assemblyPath check breaking ".\\src\\$name\\$name.baseline.json"

# Emit API review artifacts
& $dotnet $apiChief $assemblyPath emit review -o ".\\artifacts\\tmp\\API.$name"

# Emit GitHub-friendly markdown diff files against a baseline
& $dotnet $apiChief $assemblyPath emit delta ".\\src\\$name\\$name.baseline.json" --diff -o ".\\artifacts\\tmp\\API.$name.Diff"

emit delta also supports passing a .json file as the current input instead of a DLL.

6. Review or clean up baseline changes

After emit baseline:

  • preserve the original BOM and trailing newline behavior of the committed file
  • revert version-only diffs in the "Name" field
  • inspect removed // instruction comments in previous baselines and carry forward any still-needed manual edits
  • if those comments reference GitHub issues, check whether the underlying issue is still open before reapplying the workaround

7. Report results clearly

  • list the processed project(s)
  • show the chosen TFM(s)
  • report the output path(s)
  • for check breaking, state pass/fail
  • for emit delta and emit delta --diff, mention that exit code 0 means changes, 2 means no changes, and -1 means an error
  • prefer emit delta --diff output because it generates ready-to-post ```diff fenced markdown split across per-type .md files