declarative-agent-developer

Files (14)

• SKILL.md
• api-plugins.md · references/
• authentication.md · references/
• best-practices.md · references/
• conversation-design.md · references/
• deployment.md · references/
• editing-workflow.md · references/
• examples.md · references/
• instruction-review.md · references/
• localization.md · references/
• mcp-plugin.md · references/
• scaffolding-workflow.md · references/
• schema.md · references/
• workspace-gates.md · references/

SKILL.md (first lines)

# 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:
```bash
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:**

1. 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.
2. Check for `m365agents.yml` or `teamsApp.yml` at the project root.
3. Check for `appPackage/declarativeAgent.json`.
4. 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](references/scaffolding-workflow.md) |
| Manifest exists with errors | **Fix** | Detect → Inform → Ask (see below). Do NOT deploy. |
| Valid project, user reports behavior issues | **Review** | → [Instruction Review](references/instruction-review.md) — run the full 5-phase review workflow |
| Valid agent project | **Edit** | → [Editing Workflow](references/editing-workflow.md) |

> **Detailed gate rules, examples, and anti-patterns:** [Workspace Gates](references/workspace-gates.md)

### 🚫 HARD REJECTION RULES — No Exceptions

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

1. **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.

2. **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.

3. **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**:

1. **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](references/schema.md).
2. **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").
3. **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](references/scaffolding-workflow.md) |
| Working with existing `.json` manifests | [Editing Workflow](references/editing-workflow.md) |
| Adding an API plugin | [API Plugins](references/api-plugins.md) |
| Adding an MCP server | [MCP Plugin](references/mcp-plugin.md) |
| Adding OAuth to an MCP or API plugin | [Authentication](references/authentication.md) |
| Reviewing or improving existing agent instructions | [Instruction Review](references/instruction-review.md) |
| User reports agent gives generic/wrong answers | [Instruction Review](references/instruction-review.md) |
| Localizing an agent into multiple languages | [Localization](references/localization.md) |
| Adding a new language to an already-localized agent | [Localization](references/localization.md) |
| Writing agent instructions | [Conversation Design](references/conversation-design.md) |

---

## 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:

```bash
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](references/schema.md) feature matrix. If the feature isn't supported in that version, **refuse** and offer to upgrade.

From microsoft/skills, MIT.

More from microsoft/skills