New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

API Surface Diff

by pnp in pnp/powershell

Compare the public cmdlet surface of the current branch against dev - names, aliases, parameters, types, mandatory flags, parameter sets, output types, permissions - and classify each change as…

MITAuto-check passedDevelopment

Install API Surface Diff

skills CLI
$ npx skills add pnp/powershell --skill api-surface-diff -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pnp/powershell api-surface-diff --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pnp/powershell.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/api-surface-diff .claude/skills/api-surface-diff && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
api-surface-diff
GitHub stars
905
Token cost
~1.1k tokens
SKILL.md length
528 words
Files
1
Skills in repo
9
Repo updated
First seen
Licence
MIT

At a glance

Compare the public cmdlet surface of the current branch against dev - names, aliases, parameters, types, mandatory flags, parameter sets, output types, permissions - and classify each change as…

  • Tasks that involve Changelog and release notes
  • SKILL.md covers Why, The surface, Classification and Reporting
  • Calls git

What it does

API Surface Diff is an agent skill from pnp/powershell. Compare the public cmdlet surface of the current branch against dev - names, aliases, parameters, types, mandatory flags, parameter sets, output types, permissions - and classify each change as breaking, behavioural or additive. Use before opening a PR, when reviewing one, or when deciding release impact and changelog wording.

Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Changelog and release notes. It works with Microsoft 365 and PowerShell. The licence is MIT.

When your agent uses it

  • Tasks that involve Changelog and release notes

Example prompts

  • “/api-surface-diff”

What it can do on your machine

Read from SKILL.md and the folder at commit 04d819a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

API Surface Diff loads about 1.1k tokens when it runs. Until then it costs about 86 tokens; SKILL.md has 528 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~86
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pnp/powershell at commit 04d819a, republished under its MIT licence (© pnp). 528 words, ~1,057 tokens.

Download SKILL.mdSave it as .claude/skills/api-surface-diff/SKILL.md (or your agent's skills folder).
name
api-surface-diff
description
Compare the public cmdlet surface of the current branch against dev - names, aliases, parameters, types, mandatory flags, parameter sets, output types, permissions - and classify each change as breaking, behavioural or additive. Use before opening a PR, when reviewing one, or when deciding release impact and changelog wording.

Playbook: api-surface-diff

Compare the public cmdlet surface of a branch against dev and classify what changed.

Why

For a PowerShell module the public surface is the contract, and it is spread over 800 files, so a breaking change arrives as an innocuous-looking one-line diff. Renaming a parameter, tightening a type, or adding Mandatory = true breaks every script in the wild that used it. Nothing in CI catches this; a human diff review reliably misses it.

The output feeds two decisions: whether the change belongs in a major release, and what the CHANGELOG.md entry must say.

Read-only. Propose the changelog line and the release call; never open the PR — see Human in the loop.

The surface

For every cmdlet class, extract:

  • Cmdlet name — from [Cmdlet(Verbs*.X, "PnPY")]
  • Aliases — [Alias(...)] on the class
  • Output type — [OutputType(typeof(T))]
  • Parameter sets — every distinct ParameterSetName, and DefaultParameterSetName
  • Per parameter: name, type, Mandatory, Position, ValueFromPipeline, ValueFromPipelineByPropertyName, parameter set membership, [Alias], [ValidateSet] values
  • Permission attributes — a narrowed scope is a surface change too: a connection that worked before may now be rejected

Build this for dev and for the branch, then diff the two structures. Diff the extracted surface, not the text — a moved method or reordered attribute is noise.

git fetch origin dev
git diff --name-only origin/dev...HEAD -- 'src/Commands/**/*.cs'

Use the three-dot form so you compare against the merge base, not a moving dev.

Classification

Apply one test, from the repository's own review standard:

Does any correct usage behave differently?

Correct usage means an invocation that was working as documented. If only previously-broken usage changes — a parameter that was never honoured, an invocation that already threw — it is a fix.

Breaking (major release)

  • Cmdlet or parameter removed or renamed without an [Alias] preserving the old name
  • Parameter becomes Mandatory, or moves out of the default parameter set
  • Parameter type narrowed, or [ValidateSet] values removed
  • Positional parameter renumbered, or positional binding removed
  • Parameter sets restructured so a previously valid combination no longer binds
  • Output type changed such that a property scripts read is gone
  • Required permissions widened — an existing app registration stops being sufficient
Show full SKILL.md (193 more words)Show less

Behavioural (Changed in the changelog, minor release)

  • Same signature, different result, warning, or error for the same input
  • Default value changed
  • A new confirmation prompt (ShouldProcess) on a path that used to run unattended — call this out explicitly, it breaks automation without changing the signature

Additive (Added)

  • New cmdlet, new optional parameter, new parameter set that does not disturb existing binding
  • New alias

A rename with an [Alias] for the old name is additive, and this repository requires that alias. A rename without one is breaking; say so and name the alias that would fix it.

Reporting

Three sections — Breaking, Behavioural, Additive — most consequential first. For each entry:

  • Verb-PnPNoun, the member, file.cs:line
  • One sentence on what changed
  • The invocation that changes, concretely: Get-PnPFoo -Bar "x" — bound positionally before, now requires -Bar by name
  • The suggested CHANGELOG.md line, in this repo's style: cmdlet names in backticks, ending with a link to the PR or issue

Then state the release implication in one line: additive only, or a Changed entry, or a genuine major-release break.

Do not label something breaking on the strength of a diff. Name the usage that breaks, or classify it lower.

© pnp, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/api-surface-diff of pnp/powershell.

Open the folder on GitHubat commit 04d819a

Compare with similar skills

API Surface Diff next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

API Surface Diff compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
API Surface Diff this skillpnp/powershell905—~1.1kAutomated safety check: PassMIT
Release PreparationMichaelGrafnetter/DSInternals2k—~752Automated safety check: PassMIT
Validate Release-Note Code Samplesdotnet/core22k—~1.4kAutomated safety check: PassMIT
Entra Agent Idmicrosoft/GitHub-Copilot-for-Azure2553 repos~4kAutomated safety check: PassMIT
CLI Microsoft365 Scriptpnp/cli-microsoft365-mcp-server131—~3.3kAutomated safety check: PassMIT
Entra Agent Usergithub/awesome-copilot40k1 repos~2.3kAutomated safety check: PassMIT

Similar skills

  • Release Preparation

    MichaelGrafnetter/DSInternals

    Prepare the DSInternals project for a new release by updating version numbers, release notes, and changelog.

    2k GitHub stars~752 tokensUpdated 25 days ago
    DevelopmentAuto-check passed

  • Validate Release-Note Code Samples

    dotnet/core

    Official

    Builds and runs the code snippets behind .NET release-note features against the exact milestone SDK, and records what must change to move maintained samples to a new preview.

    22k GitHub stars~1.4k tokensUpdated 2 days ago
    DevelopmentAuto-check passed

  • Entra Agent Id

    microsoft/GitHub-Copilot-for-Azure

    Official

    Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant)…

    255 GitHub starsUsed in 3 repos~4k tokens
    Backend & APIsAuto-check passed

  • CLI Microsoft365 Script

    pnp/cli-microsoft365-mcp-server

    Write PowerShell scripts using CLI for Microsoft 365 commands to automate Microsoft 365 management tasks.

    131 GitHub stars~3.3k tokensUpdated 2 days ago
    Documents & OfficeAuto-check passed

  • Entra Agent User

    github/awesome-copilot

    Official

    Create Agent Users in Microsoft Entra ID from Agent Identities, enabling AI agents to act as digital workers with user identity capabilities in Microsoft 365 and Azure environments.

    40k GitHub starsUsed in 1 repo~2.3k tokens
    Documents & OfficeAuto-check passed

  • Auditing Azure Active Directory Configuration

    mukul975/Anthropic-Cybersecurity-Skills

    Auditing Microsoft Entra ID (Azure Active Directory) configuration to identify risky authentication policies, overly permissive role assignments, stale accounts, conditional access gaps, and guest…

    34k GitHub stars~3k tokensUpdated 1 mo ago
    Backend & APIsAuto-check passed

More from pnp/powershell

All 9 skills in this repo

  • Cmdlet Scaffolder

    pnp/powershell

    Generate a new PnP PowerShell cmdlet modelled on an existing sibling - class with the right base class and permission attributes, the documentation page, and the changelog entry.

    905 GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed

  • Dotnet Standards

    pnp/powershell

    C 12 / .NET 8 and PowerShell cmdlet design rules for this repository - naming, output and error channels, parameter validation, ShouldProcess, async, culture, cross-platform and ALC constraints.

    905 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed

  • Issue Triage

    pnp/powershell

    Take a PnP PowerShell GitHub issue, find the cmdlet that owns it, trace the code path, and decide whether the cause is in this repo or in PnP Framework, PnP Core SDK or the service.

    905 GitHub stars~1.8k tokensUpdated yesterday
    Auto-check passed

  • New Cmdlet

    pnp/powershell

    The conventions a PnP PowerShell cmdlet must satisfy - base class selection, permission attributes, PipeBinds, parameter validation, Graph and CSOM call patterns, and the documentation plus…

    905 GitHub stars~1.6k tokensUpdated yesterday
    Auto-check passed

  • Permissions Auditor

    pnp/powershell

    Audit PnP PowerShell permission attributes against the APIs a cmdlet actually calls and against its documentation.

    905 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed

  • Code Review

    pnp/powershell

    Review changes to PnP PowerShell for the failure modes this repository actually ships - silently ignored input, unpaged Graph collections, the wrong base class, permission attributes that do not…

    905 GitHub stars~2.3k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about API Surface Diff

What does API Surface Diff do?

Compare the public cmdlet surface of the current branch against dev - names, aliases, parameters, types, mandatory flags, parameter sets, output types, permissions - and classify each change as…. API Surface Diff is an agent skill from pnp/powershell. Compare the public cmdlet surface of the current branch against dev - names, aliases, parameters, types, mandatory flags, parameter sets, output types, permissions - and classify each change as breaking, behavioural or additive.

When should I use API Surface Diff?

API Surface Diff fits situations like: tasks that involve Changelog and release notes.

How do I install API Surface Diff in Claude Code?

Run `npx skills add pnp/powershell --skill api-surface-diff -a claude-code`. Or copy the skill folder (.agents/skills/api-surface-diff in pnp/powershell) into .claude/skills/api-surface-diff in your project. Claude Code loads it when a task matches its description.

How do I install API Surface Diff in Codex?

Run `npx skills add pnp/powershell --skill api-surface-diff -a codex`. Or copy the skill folder (.agents/skills/api-surface-diff in pnp/powershell) into .agents/skills/api-surface-diff in your project. Codex loads it when a task matches its description.

Can I use API Surface Diff in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pnp/powershell --skill api-surface-diff -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/api-surface-diff, .gemini/skills/api-surface-diff, .github/skills/api-surface-diff and .opencode/skills/api-surface-diff in your project.

What does API Surface Diff need to run?

Going by SKILL.md and its folder, API Surface Diff needs the command-line tools its instructions call (git).

Does API Surface Diff access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is API Surface Diff safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does API Surface Diff use?

API Surface Diff is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does API Surface Diff use?

About 1.1k tokens (SKILL.md is roughly 4.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to API Surface Diff?

Skills that share tags, products or a category with API Surface Diff: Release Preparation (MichaelGrafnetter/DSInternals, 2k stars), Validate Release-Note Code Samples (dotnet/core, 22k stars), Entra Agent Id (microsoft/GitHub-Copilot-for-Azure, 255 stars) and CLI Microsoft365 Script (pnp/cli-microsoft365-mcp-server, 131 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains API Surface Diff?

pnp (a GitHub organization) maintains it in pnp/powershell, which has 905 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 6, 2026.

Source: pnp/powershell on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.