Declarative Agent Developer

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Software development
MIT
Low risk

From the author

Create, build, deploy, and localize declarative agents for M365 Copilot and Teams. USE THIS SKILL for ANY task involving a declarative agent — including localization, scaffolding, editing manifests, adding capabilities, and deploying. Localization requires tokenized manifests and language files that only this skill knows how to produce. Triggers: "create agent", "create a declarative agent", "new declarative agent", "scaffold an agent", "new agent project", "add a capability", "add a plugin", "configure my agent", "deploy my agent", "fix my agent manifest", "edit my agent", "localize my agent", "add localization", "translate my agent", "multi-language agent", "add an API plugin", "add an MCP plugin", "add OAuth to my plugin", "review instructions", "improve instructions", "fix my instructions"

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The declarative-agent-developer skill provides a structured workflow for managing the lifecycle of M365 Copilot and Teams declarative agents. It utilizes the M365 Agent Toolkit (ATK) CLI to handle project scaffolding, manifest management, API plugin integration, and deployment. The skill enforces strict workspace validation, requiring specific project structures before allowing modifications, and provides standardized protocols for error handling, localization, and authentication configuration.

What it does

Scaffolds new declarative agent projects using the ATK CLI.
Manages and validates declarativeAgent.json manifests.
Integrates API plugins and MCP servers into existing agent projects.
Configures OAuth authentication for secure plugin communication.
Handles localization of agent manifests and language files.
Deploys agents to local environments for testing and validation.

When to use it

When creating a new declarative agent project for M365 Copilot or Teams.
When adding new capabilities, API plugins, or MCP servers to an existing agent.
When updating agent instructions or conversation starters.
When localizing an agent for multiple languages.
When troubleshooting or fixing errors in an agent manifest.

Advantages

Ensures consistent project structure through mandatory workspace checks.
Automates complex tasks like API plugin registration and OAuth setup.
Provides a clear, step-by-step protocol for error detection and resolution.
Facilitates standardized deployment and testing workflows.
Maintains schema compatibility by checking version requirements before feature implementation.

Usage examples

“Create a new declarative agent project.”: The agent will initialize a new project structure, including the necessary manifest files, provided the workspace is empty and valid for agent development.
“Add an API plugin to my agent using this OpenAPI spec URL.”: The agent will use the ATK CLI to integrate the specified API, map the requested operations, and prompt for necessary metadata updates.
“Localize my agent into French.”: The agent will generate the required tokenized manifests and language files to support French localization.
“Deploy my agent to the local environment.”: The agent will run the provisioning command and provide the M365 test link for the deployed agent.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/declarative-agent-developer/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip declarative-agent-developer.zip -d .agents/skills

Documentation by Microsoft

M365 Agent Developer

Telemetry Tagging

Before running any atk CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:

export ATK_CLI_SKILL=true

Run this once at the start of the session. All subsequent atk commands in the same terminal will inherit it.

⛔ Workspace Check — MANDATORY FIRST STEP

Before doing ANYTHING, check the workspace files to fingerprint the project:

Run npx -y --package @microsoft/m365agentstoolkit-cli atk --version to confirm ATK CLI is installed. If not found → Stop. Tell the user to install ATK.
Check for m365agents.yml or teamsApp.yml at the project root.
Check for appPackage/declarativeAgent.json.
Check for non-agent indicators (package.json with express/react/next, src/index.js, app.py, etc.)

Then follow the decision gate:

Condition	Gate	Action
Non-agent project files, no `appPackage/`	Reject	Text-only response. No files, no commands.
No manifest, user wants to edit/deploy	Reject	Text-only response. Explain manifest is missing.
No manifest, user wants new project	Scaffold	→ Scaffolding Workflow
Manifest exists with errors	Fix	Detect → Inform → Ask (see below). Do NOT deploy.
Valid project, user reports behavior issues	Review	→ Instruction Review — run the full 5-phase review workflow
Valid agent project	Edit	→ Editing Workflow

Detailed gate rules, examples, and anti-patterns: Workspace Gates

🚫 HARD REJECTION RULES — No Exceptions

These rules override ALL other instructions. If any of these apply, you MUST stop immediately.

NEVER create declarativeAgent.json yourself. If the manifest is missing and the user asked to edit/modify/deploy, respond with text only: explain the manifest is missing, suggest npx -y --package @microsoft/m365agentstoolkit-cli atk new or starting from scratch. Do NOT create the file, do NOT create appPackage/, do NOT "help" by scaffolding implicitly.
NEVER create files in a non-agent project. If the workspace is an Express/React/Django/etc. app without appPackage/, your response must be text-only. Do NOT create any files, do NOT run any commands.
NEVER deploy when errors exist. If the agent manifest has errors, STOP. Do NOT run npx -y --package @microsoft/m365agentstoolkit-cli atk provision — not "to test", not "to demonstrate the error", not "to see what happens". Report the errors and ask the user how to proceed.

🔍 Detect → Inform → Ask (Error-Handling Protocol)

When you encounter ANY problem (missing files, malformed JSON, validation errors, incompatible features), you MUST follow this sequence in order:

Detect — Identify the specific problem. For JSON issues, attempt to parse the file and report syntax errors. For missing fields, check the manifest against the Schema.
Inform — Tell the user BEFORE taking any action. Describe exactly what is wrong ("declarativeAgent.json has malformed JSON: missing comma on line 12, unclosed array on line 18").
Ask — Wait for the user's response before making changes. Do NOT silently fix, auto-correct, or work around the problem.

This protocol applies to:

Missing declarativeAgent.json → Detect (file not found) → Inform ("no manifest found") → Ask ("would you like to create a new agent?")
Malformed JSON → Detect (parse errors) → Inform (list specific syntax issues) → Ask ("should I fix these syntax errors?")
Validation errors → Detect (parse and check manifest) → Inform (list all errors) → Ask ("how would you like to fix these?")
Version incompatibility → Detect (feature requires newer version) → Inform ("this feature requires v1.6, your agent is v1.4") → Ask ("should I upgrade?")

Phase Routing

Scenario	Workflow Reference
Creating a NEW project from scratch	Scaffolding Workflow
Working with existing `.json` manifests	Editing Workflow
Adding an API plugin	API Plugins
Adding an MCP server	MCP Plugin
Adding OAuth to an MCP or API plugin	Authentication
Reviewing or improving existing agent instructions	Instruction Review
User reports agent gives generic/wrong answers	Instruction Review
Localizing an agent into multiple languages	Localization
Adding a new language to an already-localized agent	Localization
Writing agent instructions	Conversation Design

ATK CLI Setup

Before running any ATK commands, check if the ATK CLI is available by running npx -y --package @microsoft/m365agentstoolkit-cli atk --version. If not found, STOP and tell the user — do NOT attempt to install it yourself.

All commands use the npx -y --package @microsoft/m365agentstoolkit-cli atk prefix (e.g., npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local).

Critical Rules

1. Deploy After EVERY Edit

After ANY change to files in appPackage/, you MUST deploy and show the test link before responding:

npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false

Then read M365_TITLE_ID from env/.env.local and ALWAYS present the review UX:

✅ Agent deployed successfully!

🚀 Test Your Agent in M365 Copilot:
🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID}

⛔ Never respond without this link. If you deployed, the test link MUST appear in your response. This is not optional — it is how the user tests their agent.

If the manifest has errors → STOP. Fix errors. Do NOT deploy.
Exception: user explicitly asks you not to deploy

2. Never Invent Content or Create Missing Files

Do NOT invent placeholder names, descriptions, or instructions
Do NOT create declarativeAgent.json or appPackage/ if they don't exist — this is a REJECT scenario, not a "help by creating" scenario
If required fields are missing, report the gaps, and ASK the user
If JSON is malformed, follow Detect → Inform → Ask: parse the file first, tell the user what's broken, then ask before fixing. Use surgical edits (not rewrites)
⛔ NEVER set placeholder values for environment variables that are populated by automation (e.g., <PREFIX>_MCP_AUTH_ID, TEAMS_APP_ID). Leave them empty (VAR_NAME=). Placeholders will be treated as real values and will NOT be overwritten by provisioning.

3. Schema Version Compatibility

Before adding ANY feature, read the version field in declarativeAgent.json and check the Schema feature matrix. If the feature isn't supported in that version, refuse and offer to upgrade.

Key version gates:

sensitivity_label, worker_agents, EmbeddedKnowledge → v1.6 only
Meetings → v1.5+
ScenarioModels, behavior_overrides, disclaimer → v1.4+
Dataverse, TeamsMessages, Email, People → v1.3+

4. Use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` for API Plugins — NEVER Create Plugin Files Manually

You are forbidden from manually creating ai-plugin.json, OpenAPI specs, adaptive cards, or editing the actions array. Use the CLI:

# ⛔ Always list ALL operations in a single call — NEVER run separate calls per operation
npx -y --package @microsoft/m365agentstoolkit-cli atk add action --api-plugin-type api-spec --openapi-spec-location URL --api-operation "GET /path,POST /path,PATCH /path/{id},DELETE /path/{id}" -i false

Run a single npx -y --package @microsoft/m365agentstoolkit-cli atk add action call per OpenAPI spec, listing all operations as a comma-separated list in --api-operation. Never run separate npx -y --package @microsoft/m365agentstoolkit-cli atk add action calls for different operations from the same spec — this creates multiple plugins instead of one. If npx -y --package @microsoft/m365agentstoolkit-cli atk add action fails, report the error; do NOT fall back to manual creation.

Exception: MCP servers are not supported by npx -y --package @microsoft/m365agentstoolkit-cli atk add action. Use the MCP Plugin workflow instead.

5. MCP Server Integration

When the user mentions an MCP server URL, follow the MCP Plugin workflow. You MUST discover tools via the MCP protocol handshake (initialize → notifications/initialized → tools/list) — NEVER fabricate tool names/descriptions. For authenticated MCP servers, follow the authentication guide to configure OAuth.

6. Always Update Instructions & Starters After Changes

Adding a capability or plugin without updating instructions is incomplete. After ANY change:

Update instructions to describe the new/changed functionality — every data source should have clear intent coverage (WHEN and WHY to use it) per the Instruction Review quality bar. Built-in capabilities don't need exact names; actions/plugins should be named.
Do NOT list tool names, descriptions, or parameters in instructions — these are already in the plugin metadata (ai-plugin.json, MCP manifests, capability config). Instructions should contain decision logic only: WHEN to use each tool, chaining rules, and failure handling.
Stay within the 8,000-character instruction limit — if close to the limit, cut tool descriptions first
Add at least 1 conversation starter per added capability/plugin
Remove starters that reference removed capabilities
Run the Diagnostic Checklist against the updated instructions to verify quality

7. App Name Requirement

Always update the app name and description to something meaningful. Never leave defaults like "My Agent".

References

Shared

Authentication — OAuth discovery, credentials, oauth/register lifecycle, OAuthPluginVault
Best Practices — Security, performance, testing, compliance
Conversation Design — Authoring instructions and conversation starters from scratch
Instruction Review — Auditing, diagnosing, and improving existing instructions; anti-pattern detection; before/after rewrites
Deployment — ATK CLI workflows, environments, CI/CD
Localization — Multi-language support, tokenized manifests, language files
Workspace Gates — Detailed gate rules, examples, anti-patterns

Scaffolding

Scaffolding Workflow — Step-by-step scaffolding instructions, naming rules, error handling

JSON Development

Editing Workflow — Step-by-step JSON development instructions
Schema — Official JSON schema for agent manifests
API Plugins — OpenAPI integration for JSON agents
MCP Plugin — MCP server integration with RemoteMCPServer, OAuth, response semantics, logo handling
Examples — JSON manifest examples

Files

ATTRIBUTION.mdAdded by AutoGineer922 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md12.6 KiB
references/api-plugins.md36.2 KiB
references/authentication.md9.0 KiB
references/best-practices.md3.5 KiB
references/conversation-design.md15.6 KiB
references/deployment.md12.7 KiB
references/editing-workflow.md15.1 KiB
references/examples.md11.2 KiB
references/instruction-review.md45.0 KiB
references/localization.md18.4 KiB
references/mcp-plugin.md38.3 KiB
references/scaffolding-workflow.md8.4 KiB
references/schema.md3.5 KiB
references/workspace-gates.md9.2 KiB

references/conversation-design.md

Conversation and Instruction Design for M365 Agents

Based on the official Microsoft guidance: Write effective instructions for declarative agents

Agent Instructions

The instructions field in declarativeAgent.json references an external instructions.txt file. This keeps the JSON manifest clean and makes instructions easy to edit. This is the most critical aspect of agent design.

Instruction Limits and Token Budget

Instructions are limited to 8,000 characters. Every character counts — be concise and deliberate about what goes into instructions.txt.

⛔ Do NOT duplicate tool/capability metadata in instructions. Tool names, descriptions, parameters, and schemas are already available to the orchestrator through ai-plugin.json (description_for_model), MCP plugin manifests (mcp_tool_description.tools[]), and capability configuration in the agent manifest. Listing them in instructions wastes the 8,000-character budget.

Instructions should contain decision logic only: WHEN to use each capability, HOW to chain them, and WHAT to do on failure. See Instruction Review for the full anti-pattern catalog.

Instruction Structure

In declarativeAgent.json, reference the instructions file using ${{file:instructions.txt}}:

{
  "instructions": "${{file:instructions.txt}}"
}

Then create appPackage/instructions.txt with the actual instructions in Markdown format.

Instruction Components

A well-structured set of instructions ensures the agent understands its role, the tasks it should perform, and how to interact with users. The main components are:

Required:

Purpose — What goal must the agent accomplish?
General guidelines — Tone, restrictions, and general directions
Skills — What capabilities and actions does the agent have?

When relevant:

Step-by-step instructions
Error handling and limitations
Interaction examples
Nonstandard terms / domain vocabulary
Follow-up and closing behavior

Best Practices for Instructions

1. Use Clear, Actionable Language

Focus on what Copilot should do, not what to avoid.
Use precise, specific verbs: "ask", "search", "send", "check", "use".
Supplement with examples to minimize ambiguity.
Define any terms that are nonstandard or unique to the organization.

❌ Vague: "Help users with their questions" ✅ Specific: "Answer questions about company policies using documents from the HR SharePoint site. If the answer isn't in the documents, direct users to [email protected]"

2. Build Step-by-Step Workflows with Transitions

Break workflows into modular, unambiguous, and nonconflicting steps. Each step should include:

Goal: The purpose of the step.
Action: What the agent should do and which tools to use.
Transition: Clear criteria for moving to the next step or ending the workflow.

3. Use Strict Structure

Structure is one of the strongest signals used to interpret intent:

Use sections to group related tasks into logical categories, without implying sequence.
Use bullets for parallel tasks that can be completed independently. Avoid numbering that might introduce unintended order.
Use steps for actions that must occur in a required sequence, and reserve them only for true workflows.

4. Make Tasks Atomic

Break multiaction instructions into clearly separated units.

Instead of: "Extract metrics and summarize findings."
Use separate steps:
1. Extract metrics.
2. Summarize findings.

5. Specify Tone, Verbosity, and Output Format

If you don't specify these, the model might infer them inconsistently. Always specify:

Tone: professional and concise
Output: Three bullet points per section
Constraint: Return only the requested format; no explanations

6. Structure Instructions in Markdown

Use Markdown for emphasis and clarity:

Use #, ##, ### for section headers
Use - for unordered lists and 1. for numbered lists
Highlight tool or system names with backticks (e.g., Jira, ServiceNow)
Make critical instructions bold with **

7. Provide Clear Intent for Each Data Source

Describe the purpose and context for each data source the agent can use. You don't need to use the exact capability names from the manifest — M365 Copilot maps them internally. What matters is clear intent: when and why each data source should be used.

Actions/plugins: Reference by name — "Use Jira to fetch tickets."
Copilot connector knowledge: Reference by connector name — "Use ServiceNow KB for help articles."
SharePoint/OneDrive: Describe the data source — "Search internal HR policy documents" or "Reference company documents in SharePoint."
Email: Describe the scenario — "Check user emails for relevant information."
Teams messages: "Search Teams channels and chat messages." (messages only — NOT transcripts)
Meetings: "Check calendar events, attendees, and meeting transcripts." (transcripts come from Meetings, not TeamsMessages)
Code interpreter: "Use code interpreter to generate charts."
People knowledge: "Look up people in the organization for contact info."

Common mistake: Assuming meeting transcripts are part of TeamsMessages. Transcripts are retrieved through the Meetings capability. TeamsMessages covers channel posts, DMs, and meeting chat messages only. See the Capability Reference for the full mapping.

8. Provide Examples

For simple scenarios, examples aren't needed.
For complex scenarios, use few-shot prompting — give more than one example to illustrate different aspects or edge cases.

9. Control Reasoning Through Phrasing

Your wording signals how much reasoning the model should apply:

Deep reasoning:

Use deep reasoning. Break the problem into steps, analyze each step, evaluate alternatives, and justify the final decision. Reflect before answering.
Task: Determine the optimal 3-year migration strategy given constraints A, B, and C.

Moderate reasoning (balanced):

Provide a concise but structured explanation. Include a short summary, 3 key drivers, and a final recommendation. No step-by-step reasoning required.
Task: Explain the tradeoffs between solution X and Y.

Fast and minimal reasoning:

Short answer only. No reasoning or explanation. Provide the final result only.
Task: Extract the product name and renewal date from this paragraph.

10. Add a Self-Evaluation Step

A self-check step reinforces completeness. For example:

Before finalizing, confirm that all items from Section A appear in the summary.

11. Iterate on Your Instructions

Developing instructions is an iterative process:

Create instructions and conversation starters following this guidance.
Publish your agent.
Test your agent:
- Compare results against Microsoft 365 Copilot.
- Verify conversation starters work as expected.
- Verify the agent acts according to instructions.
- Confirm prompts outside conversation starters are handled appropriately.
Iterate on instructions to further improve output.

Example Instructions

The following example is for an IT help desk agent:

appPackage/instructions.txt:

# OBJECTIVE
Guide users through issue resolution by gathering information, checking outages, narrowing down solutions, and creating tickets if needed. Ensure the interaction is focused, friendly, and efficient.

# RESPONSE RULES
- Ask one clarifying question at a time, only when needed.
- Present information as concise bullet points or tables.
- Avoid overwhelming users with details or options.
- Always confirm before moving to the next step or ending.
- Use tools only if data is sufficient; otherwise, ask for missing info.

# WORKFLOW

## Step 1: Gather Basic Details
- **Goal:** Identify the user's issue.
- **Action:**
  - Proceed if the description is clear.
  - If unclear, ask a single, focused clarifying question.
    - Example:
      User: "Issue accessing a portal."
      Assistant: "Which portal?"
- **Transition:** Once clear, proceed to Step 2.

## Step 2: Check for Ongoing Outages
- **Goal:** Rule out known outages.
- **Action:**
  - Query `ServiceNow` for current outages.
  - If an outage is found:
    - Share details and ETA.
    - Ask: "Is your issue unrelated? If yes, I can help further."
    - If yes, go to Step 3. If no/no response, end politely.
  - If none, inform the user and go to Step 3.

## Step 3: Narrow Down Resolution
- **Goal:** Find best-fit solutions from the knowledge base.
- **Action:**
  - Search `ServiceNow KB` for related articles.
  - **Iterative narrowing:** Don't list all results. Instead:
    - Ask clarifying questions based on article differences.
    - Eliminate irrelevant options with user responses.
    - Repeat until the best solution is found.
  - Provide step-by-step fix instructions.
  - Confirm: "Did this help? If not, I can go deeper or create a ticket."

## Step 4: Create Support Ticket
- **Goal:** Log unresolved issues.
- **Action:**
  1. Map category and subcategory from the `sys_choice` SharePoint file.
  2. Fetch user's UPN (email) with the people capability.
  3. Fill the ticket with: Caller ID, Category, Subcategory, Description, attempted steps, error codes.
- **Transition:** Confirm ticket creation and next steps.

# OUTPUT FORMATTING RULES
- Use bullets for actions, lists, next steps.
- Use tables for structured data where UI allows.
- Avoid long paragraphs; keep responses skimmable.
- Always confirm before ending or submitting tickets.

Instruction Design Patterns

Pattern 1: Deterministic Workflows

Remove ambiguity by defining atomic steps, explicit formulas, and required validation:

## Task: Metrics and ROI (Deterministic)

### Definitions (Do not invent)
- Metrics to compute: [Metric1], [Metric2], [Metric3]
- ROI definition: ROI = (Benefit - Cost) / Cost
- Source of truth: Use ONLY the provided document(s) for inputs

### Steps (Sequential — do not reorder)
Step 1: Locate inputs for [Metric1-3] in the document. Quote the source.
Step 2: Compute [Metric1-3] exactly as defined. If any input is missing, stop and ask.
Step 3: Compute ROI using the definition above. Do not substitute other formulas.
Step 4: Output ONLY the table in the format below.

### Final check (Self-evaluation)
Before finalizing: confirm every metric has (a) a value, (b) a source, and (c) no assumptions.

Pattern 2: Parallel vs Sequential Structure

Make sure the model separates parallel and sequential logic:

## Section A — Extract Data
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.

## Section B — Build the Summary (Sequential)
**Step 1:** Integrate findings from Section A.
**Step 2:** Produce the 2-page call prep summary.

Pattern 3: Explicit Decision Rules

Add if/then rules to prevent unintended model interpretation:

Read the product report.
Check category performance.
If performance is stable or improving, write the summary section.
If performance declines or anomalies are detected, write the risks/issues section.

Pattern 4: Output Contract

Define shape, structure, tone, and allowed content:

## Output Contract (Mandatory)
Goal: [one sentence]
Format: [bullet list | table | 2 pages | JSON]
Detail level: [short | medium | detailed] — do not exceed [X] bullets per section
Tone: [Professional | Friendly | Efficient]
Include: [A, B, C]
Exclude: No extra recommendations, no extra context, no "helpful tips"

Pattern 5: Self-Evaluation Gate

Add an explicit self-check step before responding:

## Final Check: Self-Evaluation
Before finalizing the output, review your response for completeness, ensure that all Section A elements are accurately represented, check for inconsistencies, and revise if needed.

Pattern 6: Literal-Execution Header

Use when an agent shows inference drift or step reordering, especially after a model update:

Always interpret instructions literally.
Never infer intent or fill in missing steps.
Never add context, recommendations, or assumptions.
Follow step order exactly with no optimization.
Respond concisely and only in the requested format.
Do not call tools unless a step explicitly instructs you to do so.

Conversation Starters

Conversation starters are pre-written prompts that users can click to begin conversations. They showcase the agent's capabilities and guide users toward productive interactions. Defined in the conversation_starters array in declarativeAgent.json.

Best Practices

1. Showcase Different Capabilities

{
  "conversation_starters": [
    {
      "title": "Employee Handbook",
      "text": "What are the latest updates to the employee handbook?"
    },
    {
      "title": "Leadership Emails",
      "text": "Summarize emails from the leadership team this week"
    },
    {
      "title": "My Tickets",
      "text": "Show me open support tickets assigned to me"
    },
    {
      "title": "Satisfaction Trends",
      "text": "Analyze customer satisfaction trends from last month"
    }
  ]
}

2. Make Them Specific and Actionable

❌ Too vague: "Help me with something" ❌ Too broad: "Tell me about the project" ✅ Specific: "What are the Q4 deliverables for the Phoenix project?" ✅ Actionable: "Create a support ticket for a printer issue"

3. Cover Common Use Cases

Identify the top 3-5 tasks users will perform:

{
  "conversation_starters": [
    { "title": "Vacation Days", "text": "How many vacation days do I have left?" },
    { "title": "Remote Work", "text": "What is the remote work policy?" },
    { "title": "Expense Reports", "text": "How do I submit an expense report?" },
    { "title": "Benefits Contact", "text": "Who do I contact about benefits questions?" }
  ]
}

4. Use Natural Language

Write starters as users would naturally speak:

✅ Good: "What's the latest on Project Phoenix?" ❌ Bad: "Query project status for Phoenix"

5. Provide 3-6 Starters (Not Too Many)

Too few (<3): Users don't see the full capability range
Just right (3-6): Good variety without overwhelming
Too many (>6): Clutters UI, users won't read them all

Avoiding Common Prompt Failures

Reviewing existing instructions? If you are auditing or improving instructions that already exist (rather than writing from scratch), use the Instruction Review guide instead. It provides a diagnostic checklist, named anti-patterns, and before/after rewrite examples.

Problem	Solution
Overeager tool use — model calls tools without needed inputs	Add: "Only call the tool if necessary inputs are available; otherwise, ask the user."
Repetitive phrasing — model reuses example phrasing verbatim	Use few-shot prompting with varied examples.
Verbose explanations — model overexplains or provides excessive formatting	Add verbosity constraints and concise examples.
Too vague — instructions lack specific guidance	Add concrete examples for each capability.
Too restrictive — over-constrained agents refuse reasonable requests	Relax constraints; focus on what to do, not what to avoid.
Missing error handling — no guidance for when things go wrong	Add explicit error handling sections.
Scope creep — instructions cover too many unrelated domains	Focus on one domain; redirect out-of-scope requests.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Node.js

Security

What our scanner noticed· Low risk

Phrasing that asks for actions without confirmation
Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills · .github/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer · commit 0696600

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download declarative-agent-developer.zip