Use agent skills with App Service Builder

The Builder plugin gives your coding agent App Service Builder instructions for checking a repository, preparing its app manifest, deploying pushed source, and investigating failures. It provides one skill, app-service-builder, shared by GitHub Copilot CLI and Claude Code.

Prerequisites

• GitHub Copilot CLI or Claude Code with plugin support, or another agent that supports local Agent Skills folders. Plugin commands belong to the agent host, not Builder CLI.
• A deliberately selected local app folder. You can start with existing code or choose an optional sample. Local source inspection does not require Git initialization, a connected GitHub account, or a cloud deployment.
• Before deployment: Private Preview access, an installed Builder CLI, an authorized Azure subscription, and an available region. Reuse a resource group or create one with Azure CLI.
• For Builder CLI operations: Node.js 22 or later, Git, GitHub CLI (gh), and access to the intended GitHub repository and branch. Local manifest validation also requires a compatible .NET 10 runtime.

Installing the plugin does not install Builder CLI or grant preview access. Follow the portable Builder CLI installation instructions for the approved archive and the optional .NET runtime for local manifest commands. Use development/test workloads only. Review feature availability before choosing a workflow.

Install the Builder plugin

Choose one installation method for the host you use. The plugin marketplace is the recommended route for Copilot CLI and Claude Code. For another compatible host, use the standalone skill. Do not install both a plugin copy and a standalone copy in the same host.

GitHub Copilot CLI

Inside an interactive Copilot CLI session, run:

/plugin marketplace add microsoft/azure-app-service-builder
/plugin install builder@azure-app-service-builder

Alternatively, run the equivalent commands from your terminal:

copilot plugin marketplace add microsoft/azure-app-service-builder
copilot plugin install builder@azure-app-service-builder
copilot plugin list
copilot skill list

Confirm that the builder plugin is installed and enabled and that app-service-builder appears in the skill list. Inside a session, use /skills list or /skills info app-service-builder to inspect discovery. The plugin is registered in your personal Copilot CLI configuration, rather than copied into the app repository.

Claude Code

Inside a Claude Code session, run:

/plugin marketplace add microsoft/azure-app-service-builder
/plugin install builder@azure-app-service-builder

Review the plugin and choose the installation scope offered by the host. User scope makes it available across your projects; project scope shares the configuration with collaborators; local scope applies only to you in that project. See Claude Code installation scopes for the settings each choice writes.

Alternatively, run these commands in your terminal for the default user installation:

claude plugin marketplace add microsoft/azure-app-service-builder
claude plugin install builder@azure-app-service-builder
claude plugin list

Confirm that the builder plugin is installed and enabled. In a Claude Code session, invoke the skill with /builder:app-service-builder or ask explicitly to use App Service Builder.

If the host does not discover the skill, start a new session after installation. See the plugin installation guide for package details. This skills plugin is separate from the GitHub Copilot app canvas.

Install the standalone skill in another compatible agent

The same SKILL.md and bundled references can be installed without a plugin marketplace in a host that supports the Agent Skills format. Check your host's supported skill locations first; this is not a promise that every agent supports skills or Builder tooling.

Host	Project folder	Personal folder
Copilot CLI	.github/skills/app-service-builder/, .claude/skills/app-service-builder/, or .agents/skills/app-service-builder/	~/.copilot/skills/app-service-builder/ or ~/.agents/skills/app-service-builder/
Claude Code	.claude/skills/app-service-builder/	~/.claude/skills/app-service-builder/
Another compatible agent	Use its documented project skills directory	Use its documented personal skills directory

A project copy applies to that repository and can be committed to share with collaborators. A personal copy applies across projects for that host. Neither changes Builder access or cloud permissions.

From your app's repository root, the following macOS/Linux shell example installs a project copy for a host that discovers .agents/skills/. It downloads into a new temporary directory and refuses to replace an existing skill or symbolic link. For a different host or scope, choose its destination from the table instead.

skill_source="$(mktemp -d)" &&
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/microsoft/azure-app-service-builder.git "$skill_source" &&
git -C "$skill_source" sparse-checkout set plugin/skills/app-service-builder &&
test ! -e .agents/skills/app-service-builder &&
test ! -L .agents/skills/app-service-builder &&
mkdir -p .agents/skills &&
cp -R "$skill_source/plugin/skills/app-service-builder" .agents/skills/app-service-builder

Keep the entire app-service-builder folder, including references/; copying only SKILL.md leaves its procedures incomplete. On Windows, use Git Bash for the example or copy the complete folder from a checkout into your host's documented directory. Review the downloaded instructions before enabling them. After checking the installed copy, you can remove the temporary checkout identified by skill_source. If the destination already exists, inspect it and deliberately choose how to update it rather than overwriting it.

Restart or reload your host's skills and confirm app-service-builder appears. For Copilot CLI, run copilot skill list from the app repository, or /skills reload followed by /skills info app-service-builder inside a session. For Claude Code, the standalone invocation is /app-service-builder; the plugin invocation remains /builder:app-service-builder. Other hosts use their own discovery and invocation controls.

Standalone copies do not update through the plugin marketplace. Review upstream changes and update the complete folder deliberately; do not let an update erase local edits. See Copilot skill locations and loading and Claude Code skills for host behavior.

Activate the skill

The host uses the skill's description to decide when it is relevant. Ask explicitly for App Service Builder when you want to:

• Check repository readiness or prepare builder.yaml.
• Initialize a Builder app from GitHub source and deploy a pushed revision.
• Inspect build/deployment history, diagnose a failed operation, or recover a retained version.

A generic request such as "deploy my app" should first establish which hosting product and target you intend. For explicit invocation in Copilot CLI, ask it to use /app-service-builder. In Claude Code, use /builder:app-service-builder for the plugin or /app-service-builder for a standalone copy. Loading the skill provides instructions; it does not authorize file changes, account changes, source publication, or cloud operations.

Check your app without changing it

Open your chosen app folder in the agent host. Name App Service Builder explicitly so the agent does not choose another hosting product. For example:

Use the App Service Builder skill to inspect this selected repository.
Check the current product docs, identify its runtime and app shape, and
explain what is needed to host it. Do not edit files, install dependencies,
change accounts, publish source, or make cloud changes.

Review the result. It should identify the app's build, output, startup, and health-check requirements, along with missing prerequisites and unsupported features. The skill uses current product documentation for support boundaries and installed CLI help for command syntax. If they disagree, resolve the mismatch before continuing.

Prepare the repository

The skill can help create a missing builder.yaml or fix an existing one. It proposes file changes for you to review; it does not require a CLI generation command.

Ask for a plan before authorizing changes:

Inspect this app's existing builder.yaml for App Service Builder while
preserving its framework, files, and unrelated work. Use the manifest guide
and a matching sample for configuration guidance. Explain any needed
changes and wait for my approval before editing files or executing builds.

Samples are optional structural references, not a requirement to fork or replace your app. The skill checks the selected sample's README, root builder.yaml, and relevant source files before suggesting adaptations. A sample is not proof that every runtime version or customization works on your target.

Use the manifest guide and your selected sample to configure builder.yaml. The CLI's builder manifest validate command checks an existing manifest without creating or changing it. Agent-assisted authoring is separate from this validation command. Local validation is optional and does not block ordinary app setup; it requires the separate .NET runtime described in the CLI installation instructions. Check installed command help before invocation; the agent must not invent missing commands. Review the exact diff before approving any file changes. Build execution requires separate approval because it runs repository code.

Review the resulting diff and validation results. Confirm the intended repository, branch, source root, and files before approving a commit and push. Before deployment, have the agent verify a clean checkout and that the local commit matches the pushed branch tip. Local edits are not deployed source.

Planned build-time manifest generation

Not ready for use

Builder is adding an attempt to generate a missing builder.yaml when deploying GitHub source. The planned workflow uses the selected source revision, shows the generated YAML in deployment logs, and keeps the manifest with that app version. It does not replace a checked-in manifest, and unsupported or ambiguous app shapes can still fail. Until this is available, provide builder.yaml yourself or prepare it with the skill as described above.

Plan and approve a deployment

Replace every angle-bracket placeholder in this prompt with your intended values before sending it:

Use App Service Builder to plan deployment of <owner/repository>, branch
<branch>, source root <root>, to app <app-name> in subscription
<subscription-id>, resource group <resource-group>, location <location>.
Confirm the checkout, accounts, pushed source, and current app state first.
Explain any app creation, source connection, or deployment changes separately
and wait for approval before making them. Reuse matching existing setup.

The source root is the repository directory attached to the app; use . for the repository root. Choose the location and connection settings supplied for your preview, not values inferred by the agent. An existing app should retain its configured location.

Review the target and each proposed effect before approving it. Creating an app, authorizing or connecting GitHub source, publishing code, and deploying are separate actions. If setup changes builder.yaml, review and publish it before resuming setup. Do not treat setup completion or a successful push as a completed deployment.

Verify the hosted app

Ask the agent to report the deployment result, active version, app URL, and checks it actually performed. Open the returned URL and verify the expected page or API response. Also check any configured app-owned health endpoint; do not invent one for an app that does not implement it. A successful build or accepted deployment request is not proof that the app is serving the intended content.

If an operation times out or its outcome is unknown, inspect the authoritative app and operation state before retrying. Ask for read-only diagnosis first rather than another creation or deployment request. See deployments and versions and logging and monitoring for the underlying checks.

Clean up resources

Plugin installation alone creates no Azure app. If you created a test app, confirm its exact subscription, resource group, and name before asking the agent to delete it, or follow CLI cleanup. Keep repositories, unrelated resources, and separately owned dependencies unless you explicitly intend to remove them. Deleting the Builder app does not delete external services or stop their charges.

Related content

Use the CLI reference to check commands independently of the agent. Use the app manifest guide to understand the proposed configuration. Use the sample catalog to find an optional starting point for your app shape. Use the Portal quickstart or the Builder CLI quickstart for the same tasks without an agent.