AGENTIC AI: AGENT DESIGN.MD
- 1 day ago
- 6 min read
Author: Jonathan Stuckey
Audience: Solution designer, IT Operations, Information Advisor
Reading: short-read, guidance
Microsoft’s introduction of Skills for SharePoint AI agents gave the platform story more structure and clarity. As SKILLS (MC1269209) transition to production deployment, your next focus should be on the presentation consistency in content generation - DESIGN.md.
What are Design files?
Design files are the presentation definition for Agent generated content. The "How should content look" to the SKILLS "What should I do to create content".
They encapsulate guidance for the AI agent is held in file made-up of an optional YAML font-formatter, and Markdown (for human readable design guardrails). The output is captured in .md files stored in your local SharePoint site, along with SKILLS files.
A Design file should provide direction for (generated) output on how the content should be structured, written, and presented. It combines:
Editorial guidance (tone, style, clarity)
Structural rules (sections, headings, layout)
Presentation standards (tables, formatting, visual consistency)
Design tokens (repeatable patterns for content generation)
When would I use a Design?
The decision for where and when to use Design definition is even more straight forward than a Skill. We use Designs when we want to:
minimise re-formatting of generated output (i.e. get as near-to-complete document from AI output)
add brand and language tone consistency to Agents generated content
ensure consistency with pre-defined required sections and formatting through design rules
reduce the impact of "hallucinations" (unchecked creative generation)
In the current deployment model for Copilot agents on SharePoint, is a Design would be encapsulated as part of the specialised Agent for a process being automated. The process can be thought of providing an additional presentation tier between content generation and final output.
The approach of moving style, tone and language guidance to Design.md file allows for simplification of an Agent, in the same way moving repeating actions to Skills simplifies the reusable logic loaded on initial Agent calls. Optimising calls, and operational updates, without pushing an Agent file through extensive re-testing and release processes
Design vs. Document Templates
DESIGN markdown does NOT apply a 'template' for the output, and high-quality output will still need to be married to traditional Document Templates to ensure all standards are met.
Good practice with creating a Design.md definition is to leverage you existing investment in Document templates (if you have it). Why? Because usually your key Style, and Formatting standards are encapsulated there or in Brand Guidelines (if you have these available).
An important distinction is that DESIGN files are not document templates or high-quality format output. They apply basic language and style standards on generated content.
How would I create DESIGN?
First steps are to review your current agentic guardrails for: Style, Tone and Language. Most organisations develop a basic set of minimal-accepted format options with early agents and user training on prompt creation.
Typical AI guidance for business-professional output include indication of language preferences, a business professional tone, avoidance of marketing language or hype etc.
Example - basic agent guardrails which can be used in Design.
## LANGUAGE AND TONE
Use UK English consistently. Default tone is professional-neutral. Conversational phrasing is acceptable only where it improves clarity. Avoid hype, exaggeration, or overly promotional language unless explicitly requested.
### STYLE
Writing style must prioritise clarity and completeness over brevity.
Where explanation improves understanding, use full sentences and structured paragraphs.
Do not compress ideas into artificial short bullet fragments.
## FORMATTING
Formatting hierarchy must follow:
1. Titles and section headings
2. Explanatory text (primary method)
3. Tables for structured or repeatable content
4. Bullets only for summaries, section overviews, or concise enumerationsThese guardrails can be collected into logical groupings and extracted from agents to move to a .md markdown file.
Design file structure
A well-formed DESIGN.md should be structured, explicit, and reusable. One of the easiest approaches for developing a base-line Design.md for specific scenarios is to ask Copilot to generate a Design markdown definition, using approved samples from your existing content to act as a baseline.
The following is Copilot's own example of structure for Design markdown:
1. Document control i.e. your classic document controls - owner, versions, review dates etc
2. Purpose i.e. What this design standard is used for, Intended audience
3. Output principles (Style) i.e. Rules for content, like: clarity over completeness, Professional tone etc
4. Document structure i.e. define the required sections for specific process document output
5. Formatting rules e.g. heading hierarchy, bullet-point usage
6. Language and tone including preferred output language
7. Visual patterns (design tokens) e.g. section layout, reusable table format etc
8. Constraints and exclusions
One of the easiest approaches for developing a base-line Design.md for specific scenarios is to ask Copilot to generate a Design markdown definition, using approved samples from your existing content to act as a baseline.
Suggested approach would be:
Open Copilot App (or go to Copilot Chat)
Set the conversation boundaries
Tell Copilot it is to help in creating optimised markdown files for Design
Add links (or upload) examples of final output with preferred format, structure etc
The kind of prompt wording used should be something like:
You are an expert solution builder for Copilot, SharePoint Agents and AI builds.
I am generating solution for deployment into SharePoint Online at {solution area site}.
Using Declarative Instructions create Design markdown to support {company} standard formatting for {process-output}.
Apply the brand guidelines {brand guidelines} and approved digital assets in {image asset library} for Colour palette, font details, organisation images; for document structure sections and formatting use the following exemplars {example final document 1}, {example final document 2}, {example final document 3}This follows basics of: Scope, Context, Action, Rules (reference).
What controls do we have over the DESIGN.MD?
DESIGN markdown files are managed exactly the same as we would SKILLS files, using out-of-the-box SharePoint controls. When Skills are enabled, SharePoint creates a folder in the deployed agent site’s Agent Assets library. When DESIGN files are added, they are put in an equivalent subfolder:
/sites/<site_name>/Agent Assets/DESIGN/<design_std_name>/Users with Edit permissions, and the ability to create or edit Agents, can create a Design. Each Design definition is saved as a markdown (.md) file within the Agent Assets subfolder (DESIGN), which makes it a managed content asset rather than a separate system.
Because .md (markdown) files live in SharePoint, their access is controlled by the site’s existing roles, groups, and permission levels. Andy they can be governed using Purview classification labels.
In practice, Design.md definitions are available for general use by anyone with View/Visitor access or higher privileges on the site.
Constraints and limitations
Design markdown provides an uplift over generated content output quality, but it is not a replacement for a template. Do not expect this option to substitute for fully-formatted documentation with watermarks, images, header/footer, TOC etc. It does not do that (today).
While Microsoft agentic implementation is derived from the Design Token standard, it is important to note that it does not fully implement or comply with the evolving standard.
Currently Design files deploy to site, along with Skills files, and are not available for Global (centralised) management. Management of the files should be considered with the same approach as for managing code-solution files for Agents, and Skills.
Recommendation
DESIGN files should be reviewed by business brand and communications roles.
Agent Design files are a key piece in enabling business users to scale activity with Agents. Professional and consistent output will ensure end-users avoid creeping disillusionment with AI by removing the user-loading of output formatting.
If the goal for your use of Agents in M365 is repeatable behaviour inside SharePoint, then Designs are the natural extension for your implementation, but they do not replace the need for Document templates.
Resources
Additional resources and articles:
Microsoft 365 Roadmap | Microsoft 365 (559800) - roadmap announcement
Design.md specification - Google-labs-code | GitHub - solution designer
Design Tokens Format Module 2025.10 - original standard
Disclaimer:
Generative AI was used in the creation of the title image for this this article, and first-pass quality review. All subject content was created by author, based on released information from Microsoft and direct experience in implementation. Any errors or issues with the content in this article are entirely the author's responsibility.
Want to Know What We Know? Give Us a Call!
Looking for guidance in adopting Generative AI and Agents in a robust and useful manner? Or interested in learning how to adopt them into day-to-day office productivity, or even just learn some of the tricks of the trade? Email us at hi@timewespoke.com
About the author: Jonathan Stuckey