Official agent skill

Breadcrumbs

by MicrosoftDocs in MicrosoftDocs/semantic-kernel-docs

How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.

OfficialMITAuto-check passedEducation

Install Breadcrumbs

skills CLI

$ npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install MicrosoftDocs/semantic-kernel-docs breadcrumbs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/MicrosoftDocs/semantic-kernel-docs.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/breadcrumbs .claude/skills/breadcrumbs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "breadcrumbs" agent skill from https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs into .claude/skills/breadcrumbs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "breadcrumbs", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install MicrosoftDocs/semantic-kernel-docs breadcrumbs --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/MicrosoftDocs/semantic-kernel-docs.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.github/skills/breadcrumbs .agents/skills/breadcrumbs && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "breadcrumbs" agent skill from https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs into .agents/skills/breadcrumbs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "breadcrumbs", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install MicrosoftDocs/semantic-kernel-docs breadcrumbs --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/MicrosoftDocs/semantic-kernel-docs.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.github/skills/breadcrumbs .cursor/skills/breadcrumbs && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "breadcrumbs" agent skill from https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs into .cursor/skills/breadcrumbs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "breadcrumbs", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/MicrosoftDocs/semantic-kernel-docs.git --path .github/skills/breadcrumbs

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install MicrosoftDocs/semantic-kernel-docs breadcrumbs --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/MicrosoftDocs/semantic-kernel-docs.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.github/skills/breadcrumbs .gemini/skills/breadcrumbs && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "breadcrumbs" agent skill from https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs into .gemini/skills/breadcrumbs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "breadcrumbs", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install MicrosoftDocs/semantic-kernel-docs breadcrumbs

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/MicrosoftDocs/semantic-kernel-docs.git skills-src && mkdir -p .github/skills && cp -r skills-src/.github/skills/breadcrumbs .github/skills/breadcrumbs && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "breadcrumbs" agent skill from https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs into .github/skills/breadcrumbs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "breadcrumbs", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install MicrosoftDocs/semantic-kernel-docs breadcrumbs --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/MicrosoftDocs/semantic-kernel-docs.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.github/skills/breadcrumbs .opencode/skills/breadcrumbs && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "breadcrumbs" agent skill from https://github.com/MicrosoftDocs/semantic-kernel-docs/tree/main/.github/skills/breadcrumbs into .opencode/skills/breadcrumbs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "breadcrumbs", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: breadcrumbs
GitHub stars: 264
Token cost: ~1.7k tokens
SKILL.md length: 766 words
Files: 1
Skills in repo: 7
Repo updated: Oct 7, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.

Works in 7 steps: Locate the Breadcrumb Folder → Determine Your Structure → Find Your Index Files → …
Education work in your project
SKILL.md covers Purpose, Overview, Breadcrumb Structure and Creating a Breadcrumb File, plus 5 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Breadcrumbs is an agent skill from MicrosoftDocs/semantic-kernel-docs, published by the product's own GitHub organization. How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Education. It works with Microsoft Azure. The repository describes itself as: Semantic Kernel (SK) is a lightweight SDK enabling integration of AI Large Language Models (LLMs) with conventional programming languages. The licence is MIT.

When your agent uses it

Education work in your project

Example prompts

“/breadcrumbs”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

Locate the Breadcrumb Folder
Determine Your Structure
Find Your Index Files
Add Breadcrumb Entries
Include YAML Files in Content
Set the Breadcrumb Path
Remove extendBreadcrumb

What it can do on your machine

Read from SKILL.md and the folder at commit 6997e10. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are json and yaml).
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- learn.microsoft.com
- yamllint.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Breadcrumbs loads about 1.7k tokens when it runs. Until then it costs about 37 tokens; SKILL.md has 766 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~37
When it runs · the whole SKILL.md, loaded when a task matches: ~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from MicrosoftDocs/semantic-kernel-docs at commit 6997e10, republished under its MIT licence (© MicrosoftDocs). 766 words, ~1,663 tokens.

Download SKILL.mdSave it as .claude/skills/breadcrumbs/SKILL.md (or your agent's skills folder).

name: breadcrumbs
description: How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos.

Skill: Breadcrumbs on Microsoft Learn

Purpose

This skill describes how breadcrumbs are structured, created, and configured for documentation published on Microsoft Learn. Breadcrumbs are navigation links at the top of a page that convey an article's position in the site hierarchy.

Overview

Breadcrumbs allow users to navigate through the site hierarchy back to the home page, one level at a time. Most pages should have breadcrumbs.

Pages Without Breadcrumbs

L1 pages: Microsoft Learn home, Training home, Q&A home, Code Samples home
L2 pages: Hub pages, training browse, certification browse, certification overview, Learn Events
Search results pages

Breadcrumbs on Learn are intentionally simple and flat. The general pattern is:

Learn / [Offering name]

When an offering belongs to a branded hierarchical family:

Learn / [Offering name] / [Sub-offering name]

Each breadcrumb links to a hub page or, if unavailable, a landing page in a TOC.

[!NOTE] The breadcrumb shows where the TOC sits relative to the rest of the site, not where the user is within the TOC. This is an intentional shift to keep breadcrumbs simpler, shorter, and more coherent.

By Content Type

Content Type	Structure	Example
Documentation	`Learn / Product family (if applicable) / Offering / Sub-offering (if applicable)`	`Learn / Azure / Cognitive Services / Custom Vision Service`
Training paths & modules	`Learn / Training / Learning paths & modules`	—
Training units	`Learn / Training / Learning paths & modules / Learning path name`	`Learn / Training / Learning paths & modules / Introduction to Azure fundamentals`
Certifications	`Learn / Certifications`	—
Shows	`Learn / Shows`	—
Show episodes	`Learn / Shows / Show name`	`Learn / Shows / AI Show`
Events	`Learn / Events`	—
Event sessions	`Learn / Events / Event name`	`Learn / Events / Azure Static Web Apps Anniversary`
Code samples	`Learn / Code samples`	—

Look for a breadcrumb/ folder in the root of your docset containing a toc.yml file. This folder is created during repo provisioning. In some repos the folder is called bread/.

Step 2: Determine Your Structure

Follow the patterns above. You can map breadcrumbs for all docsets in one file, or create multiple breadcrumb files for special cases.

Step 3: Find Your Index Files

Locate the index.yml or index.md files for your product or service. Their URLs are used as breadcrumb link targets.

Use this YAML syntax in /breadcrumb/toc.yml. The "Learn" crumb is added automatically at build time — do not include it.

yaml

items:
- name: Azure
  tocHref: /azure/
  topicHref: /azure/index
  items:
  - name: Azure DevOps
    tocHref: /azure/devops/
    topicHref: /azure/devops/index
    items:
    - name: Azure Boards
      tocHref: /azure/devops/boards/
      topicHref: /azure/devops/boards/index

Required Properties

Property	Description
`name`	Display text in the breadcrumb
`tocHref`	URL path corresponding to the name. Must start and end with `/`. Articles whose URL contains this value are mapped to this breadcrumb entry. Can be a relative path to the TOC folder or an absolute path from the site domain.
`topicHref`	URL that opens when a user selects the breadcrumb link. Must start with `/`, be an absolute path from the site domain, and not include a file extension.

[!IMPORTANT] Breadcrumbs do not work with nested TOCs.

[!TIP] Validate your YAML syntax with a tool like YAML Lint.

Show full SKILL.md (293 more words)Show less

Configuring docfx.json

1. Include YAML Files in Content

Ensure "**/**.yml" is in the files array of the content section:

json

"content": [
  {
    "files": ["**/**.md", "**/**.yml"],
    "exclude": ["**/obj/**"]
  }
]

Add breadcrumb_path to globalMetadata:

json

"globalMetadata": {
  "breadcrumb_path": "/<docset-base-url>/breadcrumb/toc.json"
}

The path uses the docset's base URL plus the breadcrumb folder location. The file type must be .json (not .yml).

3. Remove extendBreadcrumb

If "extendBreadcrumb": true exists in globalMetadata, remove it or set it to false. Breadcrumbs should not duplicate the TOC.

Use multiple files only for special cases. To set them up:

Create subfolders under breadcrumb/ with additional toc.yml files.
Use fileMetadata in docfx.json to map folders to breadcrumb files:

json

"fileMetadata": {
  "breadcrumb_path": {
    "folder-a/**/*.md": "/docset/breadcrumb/subfolder-a/toc.json",
    "folder-b/**/*.md": "/docset/breadcrumb/subfolder-b/toc.json"
  }
}

Relationship with TOC

The breadcrumb and TOC are separate navigation systems:

The TOC (toc.yml) controls the left-hand sidebar — showing where the user is within a docset and what sibling/child content is available.
The breadcrumb (breadcrumb/toc.yml) controls the top-of-page links — showing where the docset sits in the overall site hierarchy.

The breadcrumb's tocHref maps URL paths to breadcrumb entries. When using contextual TOCs (linking to articles in other folders/repos while preserving your docset's navigation), both the TOC and breadcrumb files must be updated together. The breadcrumb file needs a mapping so that externally linked articles show your product's breadcrumb rather than their own.

[!IMPORTANT] Breadcrumbs do not work with nested TOCs. If you nest one toc.yml inside another, the nested portion will not generate its own breadcrumb entries.

For TOC creation and contextual TOC details, see the TOC skill.

When to Apply This Skill

When onboarding a new docset and setting up initial breadcrumbs
When restructuring an existing docset's navigation hierarchy
When troubleshooting missing or incorrect breadcrumb display
When adding a new sub-offering under an existing product family

Reference

Files

Just SKILL.md in .github/skills/breadcrumbs of MicrosoftDocs/semantic-kernel-docs.

Open the folder on GitHubat commit 6997e10

Compare with similar skills

Breadcrumbs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Breadcrumbs compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Breadcrumbs this skillMicrosoftDocs/semantic-kernel-docs	264	—	~1.7k	Automated safety check: Pass	MIT	today
SDK AI Bot Eval DatasetAzure/azure-sdk-tools	134	—	~1.4k	Automated safety check: Notes	MIT	today
SDK AI Bot Run EvaluationAzure/azure-sdk-tools	134	—	~1.1k	Automated safety check: Notes	MIT	today
Azure Education HubMicrosoftDocs/Agent-Skills	777	—	~698	Automated safety check: Pass	CC-BY-4.0	2 days ago
Skill CreatorAzure/azqr	795	89 repos	~8.2k	Automated safety check: Pass	Apache-2.0	2 days ago
Microsoft Skill CreatorMicrosoftDocs/mcp	1.9k	3 repos	~2.1k	Automated safety check: Pass	CC-BY-4.0	today

Similar skills

SDK AI Bot Eval Dataset
Azure/azure-sdk-tools
Official
Create a new evaluation dataset or add cases to an existing one for the Azure SDK QA bot evaluation.
134 GitHub stars~1.4k tokensUpdated today
Knowledge ManagementAuto-check: notes
SDK AI Bot Run Evaluation
Azure/azure-sdk-tools
Official
Run Azure SDK QA bot evaluations on curated datasets locally, including a single test case.
134 GitHub stars~1.1k tokensUpdated today
Knowledge ManagementAuto-check: notes
Azure Education Hub
MicrosoftDocs/Agent-Skills
Official
Expert knowledge for Azure Education Hub development including troubleshooting, and limits & quotas.
777 GitHub stars~698 tokensUpdated 2 days ago
Auto-check passed
Skill Creator
Azure/azqr
Official
Create new skills, modify and improve existing skills, and measure skill performance.
795 GitHub starsUsed in 89 repos~8.2k tokens
Agent WorkflowsAuto-check passed
Microsoft Skill Creator
MicrosoftDocs/mcp
Official
Create agent skills for Microsoft technologies using official documentation.
1.9k GitHub starsUsed in 3 repos~2.1k tokens
Agent WorkflowsAuto-check passed
DeepTutor CLI
HKUDS/DeepTutor
Teaches the agent to set up and run DeepTutor from the command line: chat and capabilities, knowledge bases, partners, memory, sessions, notebooks and the server or Web app.
41k GitHub stars~2.8k tokensUpdated today
EducationAuto-check passed

Questions about Breadcrumbs

What does Breadcrumbs do?

How breadcrumbs work on Microsoft Learn: structure, creation, configuration in docfx.json, and best practices for documentation repos. Breadcrumbs is an agent skill from MicrosoftDocs/semantic-kernel-docs, published by the product's own GitHub organization.json, and best practices for documentation repos.

When should I use Breadcrumbs?

Breadcrumbs fits situations like: education work in your project.

How do I install Breadcrumbs in Claude Code?

Run `npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a claude-code`. Or copy the skill folder (.github/skills/breadcrumbs in MicrosoftDocs/semantic-kernel-docs) into .claude/skills/breadcrumbs in your project. Claude Code loads it when a task matches its description.

How do I install Breadcrumbs in Codex?

Run `npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a codex`. Or copy the skill folder (.github/skills/breadcrumbs in MicrosoftDocs/semantic-kernel-docs) into .agents/skills/breadcrumbs in your project. Codex loads it when a task matches its description.

Can I use Breadcrumbs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add MicrosoftDocs/semantic-kernel-docs --skill breadcrumbs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/breadcrumbs, .gemini/skills/breadcrumbs, .github/skills/breadcrumbs and .opencode/skills/breadcrumbs in your project.

What does Breadcrumbs need to run?

SKILL.md names no scripts, command-line tools or credentials: Breadcrumbs is instructions for the agent only.

Does Breadcrumbs access the network?

SKILL.md names 2 domains. As links in the text: learn.microsoft.com and yamllint.com. This is read from the text; nothing was executed.

Is Breadcrumbs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Breadcrumbs use?

Breadcrumbs is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Breadcrumbs use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Breadcrumbs?

Skills that share tags, products or a category with Breadcrumbs: SDK AI Bot Eval Dataset (Azure/azure-sdk-tools, 134 stars), SDK AI Bot Run Evaluation (Azure/azure-sdk-tools, 134 stars), Azure Education Hub (MicrosoftDocs/Agent-Skills, 777 stars) and Skill Creator (Azure/azqr, 795 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Breadcrumbs?

MicrosoftDocs (a GitHub organization, an official publisher) maintains it in MicrosoftDocs/semantic-kernel-docs, which has 264 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 7, 2026.

Source: MicrosoftDocs/semantic-kernel-docs on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Breadcrumbs

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Skill: Breadcrumbs on Microsoft Learn

Purpose

Overview

Pages Without Breadcrumbs

Breadcrumb Structure

By Content Type

Creating a Breadcrumb File

Step 1: Locate the Breadcrumb Folder

Step 2: Determine Your Structure

Step 3: Find Your Index Files

Step 4: Add Breadcrumb Entries

Required Properties

Configuring docfx.json

1. Include YAML Files in Content

2. Set the Breadcrumb Path

3. Remove extendBreadcrumb

Multiple Breadcrumb Files

Relationship with TOC

When to Apply This Skill

Reference

Files

Compare with similar skills

Similar skills

More from MicrosoftDocs/semantic-kernel-docs

Related

Questions about Breadcrumbs