Build Smarter Declarative Agents with Skills and WIQD

Your agent does not need more instructions; it needs better timing. Custom skills for declarative agents package focused instructions, resources, and optional scripts for one task, then load that expertise only when the user needs it. An HR agent can produce a parental-leave checklist without carrying an entire employee handbook into every conversation, and Work IQ Developer Tools brings that workflow into the same lifecycle you already use to build, validate, and package your agent.

What Is a Custom Skill?

A custom skill is a directory with a required SKILL.md file and optional supporting resources or scripts. Its YAML frontmatter tells the orchestrator what the skill does and when it should activate. The Markdown body contains the procedure the agent follows after activation.

That distinction is important. Your declarative agent’s main instructions still define its identity, boundaries, and always-on behavior. Skills carry detailed, task-specific playbooks that would otherwise consume the 8,000-character instruction budget.

The result is progressive disclosure:

1. The skill name and description are available for discovery.
2. The SKILL.md instructions load when the user’s request matches the skill.
3. Referenced files load only when the active skill needs them.
4. Scripts run in the secure sandbox, and only their output joins the conversation.

The agent gets more expertise without dragging every procedure into every turn.

Add a Skill to a Declarative Agent with WIQD

Custom skills are currently available through the Microsoft Frontier Preview. The WIQD integration is also landing behind preview flags, so the draft workflow starts by enabling both the WIQD command and the underlying Agents Toolkit capability.

For the current PowerShell session:

$env:WIQD_FLAG_AGENT_SKILLS = "true"
$env:TEAMSFX_AGENT_SKILLS = "true"

Then add a skill to an existing agent project:

wiqd agent add skill \
  --name "policy-explainer" \
  --description "Explains HR policies and creates manager-ready checklists"

WIQD creates the skill folder, registers it with the app package, and updates the declarative agent manifest version required by the preview capability.

appPackage/
|-- declarativeAgent.json
|-- manifest.json
`-- skills/
    `-- policy-explainer/
        `-- SKILL.md

Add a Skill with Natural Language

The CLI command is useful for automation, but you do not have to translate your intent into flags yourself. With the WIQD skill installed in a coding agent such as GitHub Copilot CLI, describe the outcome and let WIQD route the request to the same command.

The coding agent is not inventing a second workflow. It is driving wiqd agent add skill, editing the generated SKILL.md, and running the validation steps for you. Natural language becomes the interface; WIQD remains the implementation.

One Skill Folder, Two Registrations

The generated skill has one physical folder and two manifest registrations:

Registration	Location	Purpose
agentSkills[]	appPackage/manifest.json	Registers the skill folder in the Microsoft 365 app package
agent_skills[]	appPackage/declarativeAgent.json	Connects the same skill folder to the declarative agent

Both entries point to the same appPackage/skills/policy-explainer/ directory. You do not create two skills or maintain two copies.

The declarative agent registration uses manifest version 1.9:

{
  "version": "v1.9",
  "agent_skills": [
    {
      "folder": "./skills/policy-explainer"
    }
  ]
}

WIQD writes the folder registration. The skill remains scoped to the declarative agent that references it.

This is exactly the kind of plumbing I want tooling to own. The interesting work is not remembering whether an array uses camelCase or snake_case. The interesting work is designing the procedure users can trust.

Write the Skill Around a User Outcome

The generated SKILL.md is intentionally boring: frontmatter followed by Markdown. Boring is good. Boring means reviewable.

---
name: policy-explainer
description: Use when a manager asks to explain an HR policy, prepare a checklist, or identify steps that require HR review.
---

# Policy explainer

Turn a published HR policy into guidance a manager can act on.

## Workflow

1. Identify the policy and confirm that the source is current.
2. Summarize the policy in plain language.
3. Produce a checklist in the order the manager should complete it.
4. Mark any step that requires HR approval or employee-specific advice.
5. Cite the policy sections used for the answer.

## Guardrails

- Do not invent eligibility rules, dates, or approval requirements.
- If two sources conflict, show the conflict and recommend HR review.
- Do not present general policy guidance as advice for one employee.

The description is not decorative metadata. It is the trigger surface. Write it using the phrases users actually say, such as “prepare a checklist” or “what needs HR approval”, rather than a vague description like “helps with policies”.

The body should read like a playbook for a careful teammate. Use explicit steps, observable outputs, and boundaries. If the skill can silently skip a step without anyone noticing, the step is too vague.

What Users Experience

Without the skill, the agent might summarize the parental leave policy correctly and stop. That is useful, but the manager still has to convert a page of policy language into an actual plan.

With the skill, the same request activates a structured workflow:

The user did not ask for a skill. The user asked for an outcome. Skills let the agent recognize that outcome and apply the right expertise without making the user learn your implementation.

Why Skills Make Declarative Agents More Useful

Skills improve the experience in ways users can feel:

• More focused answers: The agent loads the procedure for the current task instead of considering every workflow at once.
• More repeatable outcomes: A checklist follows the same sequence for the first user and the fiftieth user.
• More room for depth: Detailed procedures move out of the main instructions, where they compete with persona, scope, safety, and response rules.
• Better maintenance: A change to the parental leave workflow lives in one named artifact instead of a paragraph hidden inside a large instruction file.
• Safer automation: Resources, scripts, and guardrails travel with the procedure that depends on them.

This does not make the agent magically correct. It makes the behavior easier to specify, review, validate, and improve. That is a much better kind of magic.

Validate the Skill, Not Just the Agent

Static manifest validation is not enough for the complete skill package. Build the package and run deep validation so the platform checks the agentSkills[] registration, folder, SKILL.md, and frontmatter together:

wiqd agent package --env local
wiqd agent validate --mode deep

Deep validation catches the boring mistakes that become spectacularly annoying during publishing: a missing folder, a lowercase skill.md, invalid YAML, a frontmatter name that does not match the folder, or an empty description.

During preview, also design within the documented boundaries:

• An agent can have up to eight custom skills.
• Skill instructions must stay under 20,000 characters.
• The complete Agents Toolkit app package must stay under 10 MB.
• Skill scripts cannot access the network, install packages, or make authenticated calls.
• Agents that combine custom skills with embedded files are not supported yet.

Those constraints are not reasons to avoid skills. They are design pressure. Keep each skill focused, keep its resources intentional, and use API plugins or MCP servers when the task needs external systems.

The Value You Just Unlocked

• Expertise on demand: Detailed guidance enters context only when the user’s task needs it.
• Outcomes instead of instruction sprawl: Each skill is organized around a job the user wants completed.
• A WIQD-native workflow: One command creates the folder and registrations inside the existing agent project.
• Reviewable behavior: SKILL.md turns an invisible chunk of prompt text into a named artifact your team can review.
• Platform validation: Deep validation checks that the package, registration, and skill contract agree.
• A path to richer agents: Resources and sandboxed scripts let a skill carry more than prose while keeping the main agent focused.

Skills move declarative agents from “knows about this topic” toward “knows how to complete this task.” For users, that means less prompting, fewer improvised steps, and an agent that feels like it learned the job instead of merely reading the handbook.

Resources

• Custom skills in declarative agents
• Add custom skills with Microsoft 365 Agents Toolkit
• Write effective instructions for declarative agents
• Declarative agents overview
• Microsoft 365 Agents Toolkit CLI
• Explore AI Early Access in Microsoft 365
• Work IQ Developer Tools