The Microsoft Copilot Studio (MCS) Customer Advisory Team (CAT) Blog is intended to be a technical notebook for sharing quick, practical patterns and snippets that are useful in customer scenarios but don’t fit into formal documentation or guidance. The public site is https://microsoft.github.io/mcscatblog/.
More specifically, this blog is meant to be:
- Fast - A public self-controlled platform where contributors can post without waiting for approvals or adhering to external publishing cadences.
- Semi-formal - A place for semi-formal content like technical samples, workarounds, and implementation notes—that are too specific or low-level for official guidance.
- Collaborative - A collaborative space where anyone can contribute, with the idea that mature patterns might eventually flow into formal documentation or guidance.
- Connected - A way to amplify original content, such as personal videos or LinkedIn posts, provided the contributor adds meaningful value and doesn’t simply echo existing material.
This blog should not be used to compensate for missing or inaccurate documentation. Contributors should avoid cannibalizing formal guidance by clearly distinguishing between temporary specific patterns and stable high-level recommendations.
- How to use a specific combination of features in a specific use case
- Commentary on specific business use cases or agent approaches
- Point-in-time workarounds until a feature is released
- Detailed steps or updates to documentation that help resolve issues
- General feature usage guides
- High-level guidance that belongs in formal documentation
- Content that compensates for missing or inaccurate documentation (fix the docs instead)
The blog is hosted on GitHub Pages under https://microsoft.github.io/mcscatblog/. It uses Jekyll for static site generation and Chirpy as the theme.
How to contribute:
- Join the repo: Share your GitHub username with Adi to be added as a contributor.
- Clone the repo and create a new branch.
- Write your post in Markdown (.md) format under the _posts folder.
- Follow naming conventions: include the date and post name.
- Include metadata (front matter): title, date, categories, tags, author info.
- You can embed images, videos, and other static files.
- Test locally using: bundle exec jekyll serve --livereload --baseurl /mcscatblog.
- Submit a pull request and notify Adi for merging.
- Use https://chirpy.cotes.page/posts/write-a-new-post/ for formatting and embedding media.
- You can link your author profile to social accounts like Twitter/X, LinkedIn.
- GitHub Copilot (especially with the Opus model) can assist with writing posts, but it may miss some conventions, so review the guide manually.
Learn about writing new posts in Chirpy: Writing a New Post
This site is built on the upstream jekyll-theme-chirpy gem (see Gemfile). The
items below are local additions on top of the theme. They are not part of Chirpy and
will not receive upstream updates automatically.
⚠️ Use at your own peril. These customizations are maintained by us, not by the Chirpy project. When bumping thejekyll-theme-chirpyversion in theGemfile, review each item below against the new gem version. Anything that overrides or copies a theme file is the most likely thing to break.
Shows a small pill under the post title indicating whether a post is about a Classic
or Modern Copilot Studio agent. Every post must set this field — the build fails
otherwise (enforced by _plugins/validate-agent-edition.rb). Set it in front matter:
agent_edition: classic # one of: classic | modern | bothclassic— applies to classic agentsmodern— applies to modern (rebuilt) agentsboth— applies to both; renders a neutral "Classic & Modern" pill
| File | What it is | Upgrade risk |
|---|---|---|
_layouts/post.html |
Full copy of the gem's post.html with a pill block added in <header> (look for the LOCAL OVERRIDE comment). |
High. This is a frozen copy. If Chirpy changes its own post.html (new meta, TOC, image handling, etc.), those changes are silently lost. On each upgrade, diff our copy against $(bundle show jekyll-theme-chirpy)/_layouts/post.html and re-apply the pill block onto the new version. |
assets/css/jekyll-theme-chirpy.scss |
.agent-edition-pill styles appended at the end. |
Low. Self-contained classes appended after the theme import; unlikely to collide. Verify the @use 'main...' import line at the top still matches the gem. |
_plugins/validate-agent-edition.rb |
Build-time validator that fails the build if any post is missing a valid agent_edition. |
Low. Plugin-only; runs because pages-deploy.yml builds with our own Jekyll (not GitHub Pages safe mode). If you ever switch to safe mode, custom plugins won't run and this check is silently skipped. |
To re-sync the layout after an upgrade:
diff _layouts/post.html "$(bundle show jekyll-theme-chirpy)/_layouts/post.html"Re-apply the LOCAL OVERRIDE block to the new layout, then rebuild.
When installing the Chirpy theme through RubyGems.org, Jekyll can only read files in the folders
_data, _layouts, _includes, _sass and assets, as well as a small part of options of the _config.yml file
from the theme's gem. If you have ever installed this theme gem, you can use the command
bundle info --path jekyll-theme-chirpy to locate these files.
The Jekyll team claims that this is to leave the ball in the user’s court, but this also results in users not being able to enjoy the out-of-the-box experience when using feature-rich themes.
To fully use all the features of Chirpy, you need to copy the other critical files from the theme's gem to your Jekyll site. The following is a list of targets:
.
├── _config.yml
├── _plugins
├── _tabs
└── index.htmlTo save you time, and also in case you lose some files while copying, we extract those files/configurations of the latest version of the Chirpy theme and the CD workflow to here, so that you can start writing in minutes.
Check out the theme's docs.
This repository is automatically updated with new releases from the theme repository. If you encounter any issues or want to contribute to its improvement, please visit the theme repository to provide feedback.
This work is published under MIT License.