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

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

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

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

# Replace {path} with the target file

python scripts/extract_notebooks.py notebooks/intro.ipynb

To test the Python summarization agent with explicit output:

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

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

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}