Creating Declarative Agents with WIQD: From Idea to Code

Scaffolding a declarative agent takes about eight seconds. Everything you are supposed to do in the ninety seconds after scaffolding is where projects quietly go wrong: instructions pasted inline into declarativeAgent.json where nobody will ever review them, conversation starters never written, a schema version “helpfully” downgraded to something that looked more familiar. Work IQ Developer Tools, or WIQD, closes that gap with an agentic experience for declarative agent development: you describe what you want, and the tooling scaffolds a project that already follows the conventions you would have reached eventually, on your third or fourth agent, after learning the hard way.

What Is WIQD?

WIQD is the developer tooling layer for Microsoft 365 Copilot extensibility. It is an orchestrator skill that lives inside your coding agent, routes what you ask into the right lifecycle workflow, and knows the schemas, conventions, and guardrails for declarative agents. There is a CLI underneath it, and a language server, and a VS Code extension, but the primary interface is a conversation. You talk. It builds.

The important part is the routing. WIQD does not expose twenty commands you need to memorize. It exposes one entry point that figures out where you are on the journey and what you probably want next:

        Build               Improve              Preview              Publish
  create                validate             package              publish
  edit                  eval                 provision            partner-center
  instructions                               share                monitor
  capabilities
  localize

If there is no appPackage/ directory in your working folder, you are in Build. If your manifest is valid but you have no evals, you are somewhere between Build and Improve. WIQD works this out before it does anything, tells you where you are with a one-line marker, and then moves. That last part matters more than it sounds: it does not ask permission for the obvious next step.

Creating an Agent by Describing It

Here is the whole creation experience.

You did not pick a template. You did not name a folder. You did not get asked eleven setup questions. You described an agent and got a project.

The Opinionated Scaffold

The conventions are the product. Every WIQD-created agent lands on disk the same way, and the rules are non-negotiable rather than “recommended in a doc somewhere.”

Rule	Why it exists
Instructions live in instructions.txt	Instructions are prose. Prose belongs in a file you can diff, review, and comment on, not a JSON string literal
$schema and version stay verbatim	The scaffolder generates content that only validates against the schema it chose. Lowering it produces a mismatch that fails validation
At least 3 conversation starters	The scaffolding template ships zero. An agent with no starters looks broken on first open
env/.env.local and env/.env.dev from day one	Per-environment configuration is cheap now and expensive to retrofit
.github/lsp.json is written automatically	Diagnostics on the manifest, for you and for the coding agent typing beside you

That first rule is the one people underestimate. Here is what the manifest looks like:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json",
  "version": "v1.8",
  "name": "HR Policy Agent",
  "description": "Answers employee questions from the official HR policy library.",
  "instructions": "$[file('instructions.txt')]", 
  "conversation_starters": [
    { "title": "Vacation Days", "text": "How many vacation days do I have left this year?" },
    { "title": "Remote Work", "text": "What is our current remote work policy?" },
    { "title": "Expense Reports", "text": "How do I submit an expense report for travel?" }
  ]
}

And the instructions become an actual document you can read without a JSON unescaper:

You are the HR Policy Agent. You answer employee questions using only the
documents in the HR policy library.

Scope:
- Answer questions about leave, benefits, expenses, and workplace conduct.
- Do not answer questions about individual compensation or performance reviews.

Grounding rules:
- Every factual claim about policy must cite the source document.
- If the policy library does not cover the question, say so and point the
  employee at [email protected]. Never infer a policy that is not written down.

Formatting:
- Lead with the direct answer in one or two sentences.
- Follow with the relevant policy excerpt and its citation.

Editing Without Wrecking the Manifest

Creation is the easy half. The dangerous half is the fiftieth edit, when you ask for one small change and get four.

WIQD’s edit path is deliberately narrow. It reads the current state of every file it is about to touch before it writes anything, changes only what you asked for, and then verifies that related files stayed consistent. If you rename the agent, manifest.json and declarativeAgent.json move together. If you add a capability that requires a newer schema, it says so instead of silently bumping the version.

That “unchanged” line is a small thing that saves an enormous amount of review time. When your coding agent tells you exactly what it did not touch, git diff stops being a suspense novel.

There is one more piece of scaffolding worth knowing about. WIQD drops a project-scoped Copilot CLI extension into .github/extensions/ that denies raw file edits to appPackage/, m365agents.yml, and friends until the WIQD workflow has been loaded in the session. Skill discovery is best-effort, and a coding agent that decides to “just quickly fix” a manifest with a raw string replace will produce something that looks right and validates wrong. The extension makes that failure mode impossible rather than unlikely.

The One Command Worth Knowing

You can drive all of this from the terminal, and the CLI is a real first-class surface with --json output and stable exit codes for pipelines. But you mostly will not need it. This is the only bit of CLI in this post:

# Install once, then talk to it
iex "& { $(irm 'https://aka.ms/wiqd/install.ps1') }"
wiqd agent create --name "hr-policy-agent"

Everything after that install line is a sentence, not a command. The full command surface is documented at aka.ms/wiqd, and the tooling itself is open on GitHub at aka.ms/wiqd/repo if you want to read the workflows that drive these conventions or file an issue against them.

The Value You Just Unlocked

• A project that follows conventions on day one: Externalized instructions, real conversation starters, and per-environment config without a checklist.
• Reviewable agent behavior: Instructions live in a text file, so scope and tone changes show up as readable diffs in a pull request.
• Live manifest diagnostics: The language server catches schema mistakes as you type, for both you and the coding agent working alongside you.
• Scoped, honest edits: Every change reports what it touched and what it deliberately left alone.
• Guardrails that actually hold: A project-scoped extension blocks raw manifest edits that bypass the workflow, instead of trusting everyone to remember.

The shift is small to describe and large to live with. You stop authoring JSON and start describing behavior, and the conventions that used to live in your head now live in the project.

Resources

• Work IQ Developer Tools documentation
• Work IQ Developer Tools on GitHub
• Declarative agents overview
• Declarative agent manifest schema 1.8
• Writing effective agent instructions
• Build declarative agents
• Microsoft 365 Agents Toolkit overview
• Microsoft 365 Copilot extensibility overview
• Crafting effective agent instructions
• Designing conversation starters