How to use the Entra Agent User Setup agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file. The file gives an AI agent step-by-step instructions for one task, and the agent loads it when a request matches the skill's description. This skill covers one task: creating an agent user for an existing agent identity.

An agent user is a user-type account in Microsoft Entra ID. It lets an AI agent act like a digital worker for services that normally require a real user login, such as Exchange mailboxes, Teams, or org charts. Agent users receive tokens with idtyp=user, while regular agent identities receive idtyp=app.

• Verifies that the parent agent identity is a true agent identity created from an agent identity blueprint
• Creates the agent user through Microsoft Graph (beta endpoints)
• Optionally assigns a manager so the agent appears in org charts
• Optionally sets a usage location and assigns licenses for a mailbox or Teams presence

What do you need before you install it?

The skill only works in a Microsoft Entra tenant that has Agent ID capabilities. You also need an agent identity (a service principal of type ServiceIdentity) created from an agent identity blueprint. A regular app registration will not work.

You need Microsoft Graph permissions such as AgentIdUser.ReadWrite.IdentityParentedBy (the least privileged option), User.ReadWrite.All, or Organization.Read.All for license lookups. In delegated scenarios the caller needs at least the Agent ID Administrator role. The PowerShell examples use the Microsoft Graph PowerShell module (Connect-MgGraph and Invoke-MgGraphRequest). Microsoft 365 licenses are needed only if the agent user needs a mailbox or Teams presence.

How do you install the skill?

Download the ZIP for this skill from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/entra-agent-user/
• Project: .claude/skills/entra-agent-user/
• Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need to type the skill name. Describe the outcome you want in plain language that matches the skill's purpose, such as creating an agent user for an agent identity or giving an agent a mailbox. The agent will load the skill when the request matches its description.

Include the details the steps require: the tenant, the agent identity object ID, the display name you want, and the UPN domain. If you want a manager or license, say so.

• Create an agent user for my agent identity <object-id> in my Entra tenant, display name 'Invoice Agent'.
• Set up an Entra agent user so my agent can read Exchange mailboxes.
• Assign a manager and a Microsoft 365 license to the agent user I just created.

What does the process look like?

The skill follows four steps. First it checks the agent identity with a GET request to the beta servicePrincipals endpoint and confirms the type is agentIdentity. Then it creates the agent user with a POST to the users/microsoft.graph.agentUser endpoint, using accountEnabled, displayName, mailNickname, userPrincipalName and identityParentId.

Manager assignment and usage location with license assignment are optional. Usage location must be set before a license can be assigned. Keep in mind that provisioning can take from minutes to a day or more, depending on the service.

• Step 1: Verify the agent identity
• Step 2: Create the agent user (no password is set; agent users cannot have passwords)
• Step 3: Assign a manager (optional)
• Step 4: Set usage location and assign licenses (optional)

What are the safety notes?

This skill uses the network: it sends requests to Microsoft Graph. It does not run scripts itself, but its examples use PowerShell commands that you run. Creating an agent user creates an account that can hold licenses and access mail and organisational data, so treat it as a security-sensitive action.

Agent users cannot have passwords, passkeys or interactive sign-in, cannot be assigned privileged admin roles, and cannot be added to role-assignable groups. Review the request and the permissions before you approve it, and do not use this skill in production without a review.

• Use the least privileged permission that works, such as AgentIdUser.ReadWrite.IdentityParentedBy
• Check the identityParentId carefully; it must reference a true agent identity
• Do not reuse an existing user's userPrincipalName

What tips help avoid common errors?

Most failures come from the wrong ID type. If you use an app registration's appId or a regular application service principal's id, the request fails. Each agent identity can have only one agent user; a second create attempt returns 400 Bad Request.

If a mailbox, Teams or org chart entry is missing right after setup, wait. The source lists Exchange mailboxes at 5 to 30 minutes, Teams at 15 minutes to 24 hours, and org chart or People search at up to 24 to 48 hours.

• Use Connect-MgGraph with the scopes you need before running requests
• Set usageLocation before assigning a license
• You can also assign licenses in the Entra admin center under Identity → Users → All users