AI-901 Cert Buddy (Claude Code Edition)

An AI-powered study companion for the Microsoft Azure AI Fundamentals (AI-901) certification exam, built natively for Claude Code. There is no application code here. The artifacts are a memory file, subagents, slash commands, Agent Skills, hooks, and an MCP server configuration that together turn Claude Code into an interactive exam coach.

The buddy generates exam-realistic practice questions with two-phase answer evaluation, short hands-on Microsoft Foundry labs with validation gates and cleanup, and personalized study plans based on your self-assessed confidence. Every piece is original and grounded in Microsoft Learn through the free Microsoft Learn MCP server.

This repository is also a reference port. The original Cert Buddy shipped as a GitHub Copilot agent. This edition carries the same workflow to Claude Code one primitive at a time, so it doubles as a clean, usable showcase of how the Claude Code primitives fit together on a real project. See The port, primitive by primitive.

Azure knowledge prerequisites

New to Azure AI? The free AI-900 / AI Fundamentals learning paths on Microsoft Learn cover the foundational concepts that AI-901 builds on. If you already have conceptual Azure AI knowledge and basic Python, you can start with this study buddy directly.

Prerequisites

No API keys are required. The Microsoft Learn MCP server is a free hosted service with no sign-up.

Quick start

1. Clone the repository:

   git clone https://github.com/timothywarner-org/ai901-cert-buddy-claude.git
   

2. Open the folder in Claude Code:

   cd ai901-cert-buddy-claude
   claude
   

3. Claude Code auto-loads CLAUDE.md, the subagents, the slash commands, the skills, the hooks, and the .mcp.json server. Approve the project MCP server ai901buddy-mslearn when prompted. It needs no API key.

4. Start studying:

   /quiz domain=implement difficulty=medium
   

Verify setup

After opening the folder, confirm the MCP server connected:

1. Run /mcp in Claude Code.
2. Confirm that ai901buddy-mslearn shows as connected.

If it fails to connect, see Troubleshooting.

How to use it

You drive the buddy with four slash commands. Each one routes to the ai901-cert-buddy subagent and the right skill.

Practice questions

The question flow has two phases:

1. Phase 1, question. The buddy presents metadata (domain, objective, Bloom level), a scenario stem, and four answer choices (A-D). It does NOT reveal the correct answer.
2. You answer. Type your choice (for example, "B").
3. Phase 2, evaluation. The buddy tells you whether you were correct, reveals the answer, gives a two-sentence rationale for every choice, and lists Microsoft Learn references.

/quiz domain=implement difficulty=medium
/quiz domain=identify bloom=Understand

Practice labs

Labs are scoped to a single AI-901 objective, prefer keyless authentication with Microsoft Entra ID, include validation gates so you can confirm each step worked, and end with cleanup so nothing keeps billing.

/lab Foundry agent that calls a tool
/lab Azure AI Vision optical character recognition

Study plans

/plan
/plan identify=weak implement=moderate

The buddy presents the two AI-901 domains with exam weights, asks you to rate your confidence, then builds a prioritized plan with estimated hours and Microsoft Learn module links.

The port, primitive by primitive

Every headline GitHub Copilot primitive has a one-to-one Claude Code counterpart. That mapping is the reference value of this repo.

Subagents

The buddy uses three subagents in .claude/agents/:

• ai901-cert-buddy is the orchestrator. It grounds, reads, and delegates to the three skills. Its tool list is deliberately short (the three Microsoft Learn MCP tools plus Read, Grep, and Glob), because a study agent that cannot run shell commands or edit files cannot harm your machine.
• grounding-verifier is an independent checker with exactly two tools, Read and microsoft_docs_fetch. It re-fetches every cited URL and flags any retired product name. Run it after generating an item or lab for a second opinion.
• azure-principal-architect is an optional pair architect for lab design, grounded in the Azure Well-Architected Framework.

Skills

Three Agent Skills in .claude/skills/, auto-discovered by Claude Code from their SKILL.md frontmatter:

Shared reference material the skills draw on lives in .claude/skills/_references/ (the objective domain, the exam-writing rules, and the approved fictional companies).

Hooks

Two hooks in .claude/hooks/, registered in .claude/settings.json, turn the buddy's promises into guarantees:

The discipline behind both: if a guarantee has to hold, you hook it. A hook runs as your code, not the model's.

MCP server

One Model Context Protocol server is configured in .mcp.json and starts when Claude Code loads the project.

Exam resources

Key rules

The buddy enforces several non-negotiable rules across all generated content:

• Current terminology only. Retired product names are never used. Microsoft Foundry replaces Azure AI Studio, Azure AI services replaces Cognitive Services, and so on. The full rename table lives in CLAUDE.md.
• Grounded in Microsoft Learn. Every question and lab is grounded in official Microsoft Learn documentation through the MCP server before any other source. Microsoft Learn URLs are included as references.
• Original content only. The buddy never recreates, paraphrases, or references real exam questions or leaked content. Every scenario is written from scratch.
• No contractions. Generated exam content avoids contractions, per the exam-writing style guide.
• No trick wording. Negative words are avoided; when necessary, they are capitalized and bolded.
• Distractors must be real. Wrong answer choices reference actual Azure AI services and Foundry features, never invented ones.
• Labs include cleanup. Every lab ends with steps that remove the resources it created.
• Answer randomization. The correct answer position is randomized across A, B, C, and D.
• Company randomization. Fictional company names are drawn from the approved Microsoft list, not always Contoso, Ltd.

Troubleshooting

Repository structure

ai901-cert-buddy-claude/
  CLAUDE.md                          Memory: AI-901 facts, grounding rules, rename table
  .mcp.json                          Microsoft Learn MCP server (HTTP, no key)
  .claude/
    settings.json                    Hook registration (PreToolUse + PostToolUse)
    agents/
      ai901-cert-buddy.md            Orchestrator subagent
      grounding-verifier.md          Independent citation and terminology checker
      azure-principal-architect.md   Optional pair architect for lab design
    commands/
      quiz.md  lab.md  plan.md  explain.md
    skills/
      ai901-item-creator/SKILL.md    Exam question generation
      ai901-lab-creator/SKILL.md     Practice lab generation
      ai901-study-planner/SKILL.md   Personalized study plan generation
      _references/                   Objective domain, exam-writing rules, companies
    hooks/
      policy-gate.py                 PreToolUse: deny destructive Bash
      citation-audit.py              PostToolUse: log Microsoft Learn grounding
  .claude-plugin/
    plugin.json                      Publish the buddy as a plugin
    marketplace.json                 One-line install for learners
  images/                            Banner
  .editorconfig  .markdownlint.json  .gitignore
  CONTRIBUTING.md  SECURITY.md  CODE_OF_CONDUCT.md  LICENSE

Help and support

• Issues: Report a bug or request a feature
• Contributing: See CONTRIBUTING.md
• Security: See SECURITY.md
• Maintainer: Tim Warner, TechTrainerTim.com

What is new in v0.2: a custom MCP server and a deeper Claude Code surface

Version 0.2 turns the buddy from a clean port into a full reference build. New in the box:

• A custom MCP server in mcp-server/, built on the MCP Python SDK (FastMCP), exposing all three core MCP primitives at once: tools (score_answer, validate_item, next_question), resources (certbuddy://domains, certbuddy://progress, certbuddy://bank/{domain}), and prompts (quiz, exam). One optional tool, generate_item, uses the Anthropic Python SDK to author a fresh item when ANTHROPIC_API_KEY is set.
• Four hook events now: SessionStart and UserPromptSubmit keep grounding and WWL rules in front of the model, on top of the PreToolUse policy gate and PostToolUse citation audit.
• A Cert Coach output style that sets the study-coach voice.
• Turnkey Microsoft Learn grounding that travels with the repo: .mcp.json for Claude Code and .vscode/mcp.json for VS Code, both with no API key.
• Modular memory: CLAUDE.md imports .claude/rules/grounding.md.

New to the repo? Start with the TUTORIAL for a hands-on first fifteen minutes.

Enabling the local server

The Microsoft Learn MCP needs nothing. The local cert-buddy server needs its Python dependency once:

pip install -r mcp-server/requirements.txt

Then Claude Code starts it automatically from .mcp.json.

Install as a plugin

The whole buddy is packaged as an installable Claude Code plugin under plugin/ai901-cert-buddy/, generated from the project primitives by scripts/build-plugin.ps1 (or scripts/build-plugin.sh). The marketplace manifest is .claude-plugin/marketplace.json.

/plugin marketplace add timothywarner-org/ai901-cert-buddy-claude
/plugin install ai901-cert-buddy

Re-run the build script after editing any agent, command, skill, hook, or the MCP server, then commit.

Gradable labs

/lab saves each lab as a gradable document under labs/<slug>/: a learner-facing lab.md plus a canonical answer-key.json. Record your results in labs/<slug>/submission.json and run /grade <slug>. The cert-buddy MCP tool grade_lab compares your submission against the key and returns a score with a per-check breakdown. The schema is in labs/README.md.

Friendlier slash commands

Every command enumerates its options, and when you run one bare it shows a plain-English pick-list (for example, what each Bloom level means) so a beginner never has to guess. Run /quiz and accept the defaults, or pass domain=identify bloom=Remember to steer.

Social preview

The banner at images/ai901-cert-buddy.png is sized 1280x640 to double as the GitHub social-preview card. To enable it, upload that file once under Settings > General > Social preview (GitHub does not expose this as a file in the repo).