# How to Work with the AGENTS.md Automation File in ML-For-Beginners

> Learn to use the AGENTS.md automation file in ML-For-Beginners. Effortlessly configure agents for knowledge-base generation and automate content extraction processing and publishing.

- Repository: [Microsoft/ML-For-Beginners](https://github.com/microsoft/ML-For-Beginners)
- Tags: how-to-guide
- Published: 2026-02-28

---

**AGENTS.md** is the central configuration document that defines automation agents for the Instagit knowledge-base generation pipeline, enabling automated extraction, processing, and publishing of repository content through simple markdown tables.

The `microsoft/ML-For-Beginners` repository uses a sophisticated automation system to maintain its documentation and knowledge base. At the heart of this system lies [`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md), a configuration file that orchestrates how automation agents scan, extract, and transform repository content. Understanding how to work with the AGENTS.md automation file allows contributors to extend the pipeline and customize content generation workflows without modifying complex CI/CD configurations.

## Understanding the AGENTS.md File Structure

### The Instagit Pipeline Configuration

[`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md) serves as the control center for the **Instagit** knowledge-base generation pipeline. Unlike traditional CI configuration files that use YAML or JSON, this file uses readable markdown tables to define agent behavior, making it accessible to contributors without specialized tooling knowledge.

### Table Schema and Columns

Each automation agent is defined as a row in a markdown table with four specific columns:

- **Agent**: Human-readable identifier for the automation task (e.g., `Extract-Notebooks`)
- **Trigger**: File pattern or event that initiates the agent (e.g., `*.ipynb` for Jupyter notebooks)
- **Command**: Shell command or script path that executes the automation logic
- **Output**: Destination pattern where results are stored (e.g., `knowledge-base/{name}.md`)

## Defining Automation Agents in AGENTS.md

### Core Automation Tasks

Agents typically perform four categories of operations when you work with the AGENTS.md automation file:

1. **Repository Scanning**: Locating source files, Jupyter notebooks, and digital assets across the codebase
2. **Metadata Extraction**: Parsing document headings, code blocks, and YAML frontmatter from markdown files
3. **Knowledge-Base Generation**: Processing extracted data through the Instagit LLM to produce articles, FAQs, and cheat-sheets
4. **Output Publishing**: Committing generated markdown files to the `knowledge-base/` directory

### Agent Configuration Examples

To add a new agent that extracts Jupyter notebooks for the knowledge base, append the following row to [`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md):

```markdown
| Agent            | Trigger   | Command                                          | Output                |
|------------------|-----------|--------------------------------------------------|-----------------------|
| Extract-Notebooks| *.ipynb   | python scripts/extract_notebooks.py {path}      | knowledge-base/{name}.md |

```

For agents that summarize Python scripts, use a command that accepts output path parameters:

```markdown
| Agent            | Trigger   | Command                                          | Output                |
|------------------|-----------|--------------------------------------------------|-----------------------|
| Summarise-Python | *.py      | python scripts/summarise_code.py {path} --out {out}| knowledge-base/{name}_summary.md |

```

## Executing and Debugging AGENTS.md Agents

### CI/CD Pipeline Execution

When the Instagit CI/CD pipeline runs, it parses [`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md), matches **Trigger** patterns against the repository tree, and executes the corresponding **Command** for each match. The pipeline automatically captures stdout and writes results to the specified **Output** locations, then commits changes to the `knowledge-base/` folder.

### Local Testing and Debugging

You can manually execute agent commands for debugging without triggering the full CI pipeline. This is useful when developing new automation scripts or troubleshooting extraction logic.

To run the notebook extraction agent locally:

```bash

# Replace {path} with the target file

python scripts/extract_notebooks.py notebooks/intro.ipynb

```

To test the Python summarization agent with explicit output:

```bash
python scripts/summarise_code.py src/model.py --out knowledge-base/model_summary.md

```

## Key Files and Locations in the Repository

When you work with the AGENTS.md automation file, you interact with several critical components of the ML-For-Beginners repository:

- **[`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md)** – The main automation definition file located in the repository root. This file contains the markdown tables that configure all Instagit agents.

- **[`scripts/extract_notebooks.py`](https://github.com/microsoft/ML-For-Beginners/blob/main/scripts/extract_notebooks.py)** – Python script referenced by the `Extract-Notebooks` agent. This utility parses Jupyter notebook files and converts them to markdown format for the knowledge base.

- **[`scripts/summarise_code.py`](https://github.com/microsoft/ML-For-Beginners/blob/main/scripts/summarise_code.py)** – Script used by the `Summarise-Python` agent to generate concise documentation from Python source files using LLM processing.

- **`knowledge-base/`** – Destination directory where all generated markdown articles and summaries are stored. The Instagit pipeline commits new content to this folder after each successful agent execution.

## Summary

- **AGENTS.md** is the central configuration file for the Instagit automation pipeline in the ML-For-Beginners repository, using markdown tables to define agent behavior.

- Each agent row specifies four components: **Agent** (name), **Trigger** (file pattern), **Command** (execution script), and **Output** (destination path).

- Agents perform repository scanning, metadata extraction, knowledge-base generation, and output publishing to automate documentation workflows.

- You can manually test agent commands locally using `python scripts/extract_notebooks.py {path}` or `python scripts/summarise_code.py {path} --out {out}` before committing changes to [`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md).

- Generated content is stored in the `knowledge-base/` folder, which the CI pipeline commits automatically after processing.

## Frequently Asked Questions

### What is the purpose of AGENTS.md in the ML-For-Beginners repository?

[`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md) serves as the configuration hub for the Instagit knowledge-base generation pipeline. It defines automation agents that scan repository content, extract metadata from notebooks and source files, and generate structured documentation. The file enables contributors to extend automation capabilities without modifying CI/CD configuration files directly.

### How do I add a new automation agent to AGENTS.md?

To add a new agent, append a row to the markdown table in [`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md) with four columns: the **Agent** name (descriptive identifier), the **Trigger** pattern (such as `*.py` or `*.ipynb`), the **Command** (path to the script with any arguments), and the **Output** pattern (destination like `knowledge-base/{name}.md`). After committing the change, the Instagit pipeline automatically detects and executes the new agent.

### Can I run AGENTS.md agents locally without the CI pipeline?

Yes, you can execute agent commands locally for testing and debugging. Extract the **Command** from the table and run it directly in your shell. For example, use `python scripts/extract_notebooks.py notebooks/example.ipynb` to test notebook extraction, or `python scripts/summarise_code.py src/model.py --out knowledge-base/model_summary.md` to verify Python summarization. This approach allows you to validate scripts before committing changes to [`AGENTS.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/AGENTS.md).

### Where are the outputs from AGENTS.md agents stored?

The Instagit pipeline writes all generated content to the `knowledge-base/` directory at the repository root. Each agent's **Output** column defines the specific file pattern, typically using placeholders like `{name}` or `{out}` that resolve to actual filenames during execution. After successful completion, the CI system commits these markdown files to the `knowledge-base/` folder, making them available as permanent documentation assets in the repository.