edit-agent

Edit Agent Settings/Instructions

Modify agent metadata (agent.mcs.yml) or configuration (settings.mcs.yml).

Instructions

1. Auto-discover the agent directory:

   Glob: **/agent.mcs.yml
   

   NEVER hardcode an agent name. If multiple agents found, ask which one.

2. Identify what the user wants to change and read the appropriate file:

   • Instructions, display name, conversation starters, AI settings → agent.mcs.yml
   • GenerativeActionsEnabled, authentication, recognizer, capabilities → settings.mcs.yml

3. If the user wants to change the AI model, run the schema lookup tool first:

   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js models
   

   Use the output to determine the correct modelNameHint and provider values. CRITICAL: Do NOT include kind in the model block — the agent-level schema uses CurrentModelsNoKind.

4. Read the current file before making any changes.

5. Make the requested changes using the Edit tool.

Editable Fields in agent.mcs.yml

Field	Description	Example
displayName	Agent's display name	displayName: My Agent
instructions	System prompt / personality	Multi-line YAML with |
conversationStarters	Suggested conversation starters	Array of {title, text}
aISettings.model.modelNameHint	Model hint (run models command for convention)	Sonnet46, GPT5Chat
aISettings.model.provider	Model provider (required for non-OpenAI)	Anthropic

Editable Fields in settings.mcs.yml

Field	Description	Example
GenerativeActionsEnabled	Enable generative orchestration	true / false
authenticationMode	Auth mode	Integrated, None
authenticationTrigger	When to auth	Always, AsNeeded
accessControlPolicy	Access control	ChatbotReaders
configuration.aISettings.*	AI capabilities	Various booleans
configuration.settings.*.content.capabilities.webBrowsing	Web browsing	true / false

Writing Effective Instructions

For detailed guidance on writing knowledge-aware instructions, grounding directives, citation control, and scope enforcement, see instructions-guide.md.

Fields to NEVER Modify

• schemaName — This is the internal Power Platform identifier. Changing it breaks the agent.
• publishedOn — Managed by the platform.
• template — Managed by the platform.
• language — Changing this can corrupt the agent.

If the user asks to change any of these, warn them.

Example: Update Instructions

instructions: |
  You are a customer support agent for Contoso Ltd.

  Guidelines:
  - Be professional and empathetic
  - Always verify the customer's identity first
  - Escalate billing issues to a human agent