# Ai901 Cert Buddy Claude

> AI-901 (Azure AI Fundamentals) study buddy built natively for Claude Code: exam-realistic questions, Microsoft Foundry labs, and study plans, grounded in Microsoft Learn via MCP, with subagents, skills, slash commands, and deterministic hook guardrails.

- **Type:** MCP server
- **Install:** `agentstack add mcp-timothywarner-org-ai901-cert-buddy-claude`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [timothywarner-org](https://agentstack.voostack.com/s/timothywarner-org)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [timothywarner-org](https://github.com/timothywarner-org)
- **Source:** https://github.com/timothywarner-org/ai901-cert-buddy-claude

## Install

```sh
agentstack add mcp-timothywarner-org-ai901-cert-buddy-claude
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://learn.microsoft.com/credentials/certifications/azure-ai-fundamentals/)
[](https://learn.microsoft.com/credentials/certifications/azure-ai-fundamentals/)
[](https://www.claude.com/product/claude-code)
[](https://learn.microsoft.com/)
[](https://TechTrainerTim.com)

# 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](#the-port-primitive-by-primitive).

## Azure knowledge prerequisites

New to Azure AI? The free [AI-900 / AI Fundamentals learning paths](https://learn.microsoft.com/training/courses/ai-900t00) 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

| Requirement | Purpose |
| --- | --- |
| **Claude Code** | Runs the buddy: the subagents, slash commands, skills, and hooks |
| **Python 3** | Runs the two small hook scripts in `.claude/hooks/` |
| **Azure subscription** | Needed only if you want to run the practice labs against real Azure resources |

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:

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

2. Open the folder in Claude Code:

   ```bash
   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:

   ```text
   /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](#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.

| Command | What it does |
| --- | --- |
| `/quiz [count=5] [domain=...] [bloom=...] [difficulty=...]` | A short quiz (default 5 questions), one at a time with progress and an end-of-quiz score. Use `count=1` for a single question |
| `/lab [topic]` | A short, self-validating Microsoft Foundry lab with a mandatory cleanup step |
| `/plan [confidence per domain]` | A personalized study plan ordered weakest to strongest, with Microsoft Learn module links |
| `/explain [concept]` | A first-principles explanation grounded in Microsoft Learn |

### 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.

```text
/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.

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

### Study plans

```text
/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.

| GitHub Copilot primitive | Claude Code primitive | Where it lives here |
| --- | --- | --- |
| `.github/copilot-instructions.md` | **CLAUDE.md** (always-on memory) | `CLAUDE.md` |
| `.github/agents/*.agent.md` | **Subagent** | `.claude/agents/ai901-cert-buddy.md` |
| (none) | **Subagent** (verifier) | `.claude/agents/grounding-verifier.md` |
| `.github/prompts/*.prompt.md` | **Slash command** | `.claude/commands/{quiz,lab,plan,explain}.md` |
| `.github/skills/*/SKILL.md` | **Agent Skill** | `.claude/skills/ai901-*/SKILL.md` |
| `.vscode/mcp.json` | **Project MCP** | `.mcp.json` |
| CI greps | **Hooks** | `.claude/settings.json` + `.claude/hooks/*.py` |
| (none) | **Plugin and marketplace** | `.claude-plugin/` |

## 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:

| Skill | Purpose |
| --- | --- |
| **ai901-item-creator** | Exam-realistic AI-901 practice questions following the Microsoft Worldwide Learning Exam Writing Style Guide, with randomized answer positions and fictional companies |
| **ai901-lab-creator** | Short hands-on Microsoft Foundry labs with validation gates and cleanup |
| **ai901-study-planner** | Personalized study plans across the two AI-901 domains |

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:

| Hook | Event | What it does |
| --- | --- | --- |
| `policy-gate.py` | PreToolUse (Bash) | Blocks destructive shell commands before they run by returning a deny decision |
| `citation-audit.py` | PostToolUse (Microsoft Learn MCP) | Appends every grounding call and its returned URLs to `.cert-buddy/audit.log` |

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.

| Server ID | Transport | Purpose |
| --- | --- | --- |
| `ai901buddy-mslearn` | `https://learn.microsoft.com/api/mcp` (HTTP) | Free Microsoft Learn MCP server, no API key and no sign-up. Provides `microsoft_docs_search`, `microsoft_docs_fetch`, and `microsoft_code_sample_search`, which ground all content in official Microsoft documentation. |

## Exam resources

| Resource | Link |
| --- | --- |
| Azure AI Fundamentals certification | [Certification page](https://learn.microsoft.com/credentials/certifications/azure-ai-fundamentals/) |
| AI-901 study guide | [Study guide](https://learn.microsoft.com/credentials/certifications/resources/study-guides/ai-900) |
| Free practice assessment | [Practice assessment](https://learn.microsoft.com/credentials/certifications/azure-ai-fundamentals/practice/assessment) |
| Schedule your exam | [Register and schedule](https://learn.microsoft.com/credentials/certifications/register-schedule-exam) |
| Exam policies and FAQs | [Exam policies](https://learn.microsoft.com/credentials/certifications/certification-exam-policies) |
| Microsoft Learn MCP server | [Documentation](https://learn.microsoft.com/training/support/mcp) |

## 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

| Problem | Cause | Fix |
| --- | --- | --- |
| MCP server fails to connect | Network connectivity | The server is hosted at `learn.microsoft.com/api/mcp`. Confirm you have internet access, then run `/mcp` to reconnect |
| Hooks do not fire | Python not on PATH | Confirm `python3` runs in your shell. The hooks are plain Python 3, no dependencies |
| Slash commands do not appear | Project not loaded | Launch `claude` from inside the repository folder so `.claude/` is discovered |
| A skill is not used | Description mismatch | Skills are auto-selected from their `SKILL.md` description. Ask for the task directly, for example "quiz me on responsible AI" |

## Repository structure

```text
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](https://github.com/timothywarner-org/ai901-cert-buddy-claude/issues)
- **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md)
- **Security:** See [SECURITY.md](SECURITY.md)
- **Maintainer:** Tim Warner, [TechTrainerTim.com](https://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/`](mcp-server/README.md), 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**](TUTORIAL.md) 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:

```bash
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`.

```text
/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//`: a learner-facing `lab.md` plus a canonical `answer-key.json`. Record your results in `labs//submission.json` and run `/grade `. 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`](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).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [timothywarner-org](https://github.com/timothywarner-org)
- **Source:** [timothywarner-org/ai901-cert-buddy-claude](https://github.com/timothywarner-org/ai901-cert-buddy-claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-timothywarner-org-ai901-cert-buddy-claude
- Seller: https://agentstack.voostack.com/s/timothywarner-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.