Markdown w/ Frontmatter Agent Parser

[sehoon38]

Summary

Migrate to use md w/ Frontmatter instead of toml files.

Details

Markdown is increasingly becoming the industry standard. Transitioning to this format ensures consistency and simplifies the developer experience.

• replace toml-loader with agent Loader
• Flattened prompt structures to remove nested fields. system_prompt and query have been moved to the top level. Since Frontmatter relies on YAML-style indentation, flattening these fields makes them significantly easier for users to edit.
• Enabled prompt writing within the Markdown body. This provides a much better experience for drafting long-form prompts compared to multi-line strings in TOML.

Related Issues

Fixes #15968

How to Validate

• Create a directory: mkdir -p .gemini/agents
• Create a file .gemini/agents/test-agent.md

---
name: sample-agent
description: A sample agent for testing the markdown parser.
display_name: Sample Markdown Agent
tools:
  - list_directory
  - read_file
model:
  model: gemini-2.0-flash-exp
  temperature: 0.7
query: how are you?
system_prompt: |
  hello how are you
---

Also testing multi-remote agents

• create another file .gemini/agents/test-remote-agents.md

---
- kind: remote
  name: remote-agent-double-1
  description: First of two agents
  agent_card_url: https://example.com/agent-2
- kind: remote
  name: remote-agent-double-2
  description: Second of two agents
  agent_card_url: https://example.com/agent-3
---

• Run npm run preflight to ensure all tests pass.
• Verify that the agent is discovered by checking logs in debug mode.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello @sehoon38, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant refactoring of how agents are defined and loaded within the system. By transitioning from TOML to Markdown files with YAML frontmatter, the change aims to streamline the agent definition process, allowing for more intuitive system prompt specification directly within the Markdown body. This update enhances the flexibility and maintainability of agent configurations, ensuring a more robust and user-friendly approach to managing agent definitions.

Highlights

• Migration to Markdown for Agent Definitions: Agent definitions are now parsed from Markdown files with YAML frontmatter, replacing the previous TOML format.
• Renamed Loader Module: The toml-loader.ts file has been renamed to loader.ts to reflect the change in parsing format.
• Updated Parsing Logic: The parsing mechanism now uses js-yaml to extract frontmatter and can derive the system prompt from the Markdown body if not explicitly defined in the frontmatter.
• File Scanning Update: The loadAgentsFromDirectory function now specifically targets .md files for agent definitions, ignoring other file types and those prefixed with an underscore.
• Comprehensive Testing: A new test suite (loader.test.ts) has been added to thoroughly validate the new Markdown parsing and loading functionalities, replacing the deprecated TOML loader tests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +477 B (0%)

Total Size: 22.3 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	22.3 MB	+477 B (0%)
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request refactors the agent definition loader, migrating from TOML files to Markdown with YAML frontmatter, involving the replacement of the TOML parser with "js-yaml" and updates to data structures, validation schemas, and file loading logic. However, a critical insecure deserialization vulnerability was identified due to the use of yaml.load() on untrusted file content, which can lead to Remote Code Execution. A high-severity Server-Side Request Forgery (SSRF) vulnerability was also found, as the agent_card_url is not properly sanitized. Additionally, a high-severity correctness bug was identified. Immediate remediation is recommended for these issues before merging.