Create agent tips and tricks documentation

[johnlindquist]

Add comprehensive documentation with 10 advanced patterns for building powerful agents using mdflow. Covers symbol extraction, git integration, conditional prompts, composable agents, multi-file refactoring, pipeline chaining, remote schemas, interactive debugging, and multi-model orchestration.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide featuring 10 advanced agent patterns with practical examples: self-documenting agents, dynamic code review, conditional tool configuration, composable agents, multi-file refactoring, pipeline chaining, contextual commit messages, schema integration, interactive debugging, and multi-model orchestration.
  • Includes quick reference syntax guide and best practices for prompt design and agent composition.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

A new documentation file introduces 10 advanced agent patterns leveraging mdflow system features including symbol extraction, template variables, globs, conditionals, nested imports, line-range targeting, stdin chaining, remote schema integration, interactive sessions, and multi-model orchestration, with usage examples and best practices.

Changes

Cohort / File(s)	Summary
Agent Documentation docs/agent-tips-tricks.md	New file detailing advanced agent patterns with feature examples, concrete usage scenarios, quick reference syntax guide, and best practices for mdflow-based agent design

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Verify accuracy of mdflow feature descriptions and code examples
• Confirm consistency with actual system capabilities and syntax

Poem

🐰 Ten tricks for agents wise,
With templates, globs, and stdin's prize,
Nested flows and schemas bright,
Multi-models working right—
A carrot-worthy guide to might! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding documentation for agent tips and tricks, which aligns with the new docs/agent-tips-tricks.md file containing 10 advanced agent patterns.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/agent-tips-tricks-docs-01Jo4ErVnCgiG5VDjkekPuFK

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/agent-tips-tricks.md (2)

359-359: Consider rephrasing for a more formal tone.

The phrase "enables the agent to explore and fix issues autonomously" could benefit from more formal wording. Consider: "enables the agent to autonomously identify and remediate issues" or "provides the agent with autonomous issue diagnosis and repair capabilities."

This is a minor style improvement based on static analysis feedback.

---

422-450: Consider adding examples for positional mapping and clarifying system keys.

The coding guidelines mention positional mapping ($1, $2 in frontmatter to map arguments to CLI flags), but no tip demonstrates this pattern. Additionally, the documentation could clarify the distinction between system keys (_stdin, env, $1, $2, _cwd) that are consumed by mdflow versus custom template variables (_target, _env, _file, etc.) that are user-defined and passed via CLI flags. Line 387 uses _subcommand: exec without explanation—is this a system key or a template variable?

Consider adding:

1. A tip demonstrating positional mapping for CLI argument routing
2. A note in the Best Practices section clarifying the system key vs. template variable distinction
3. Documentation for _subcommand if it's a system key, or clarification if it's user-defined

This would help developers understand the full range of mdflow capabilities and write more maintainable agent configurations.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a58641b and cfccff8.

📒 Files selected for processing (1)

• docs/agent-tips-tricks.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Parse YAML frontmatter in markdown files for agent configuration
Use _ prefix for template variables (e.g., _varname) in frontmatter and body templates
System keys in agent frontmatter (_varname, _stdin, env, $1, $2, etc.) are consumed by md and not passed to the command
All non-system frontmatter keys are passed directly as CLI flags to the specified command
Use LiquidJS template syntax for variable substitution in markdown bodies (variables, conditionals, filters)
Use positional mapping ($1, $2) in frontmatter to map body or positional args to specific CLI flags
Implement imports in markdown files using syntax: basic (@./path.md), globs (@./src/**/*.ts), line ranges (@./file.ts:10-50), symbols (@./file.ts#InterfaceName), commands (!`cmd`), and URLs (@https://example.com/file.md)

Files:

• docs/agent-tips-tricks.md

🧠 Learnings (2)

📚 Learning: 2025-12-10T00:48:48.888Z

Learnt from: CR
Repo: johnlindquist/mdflow PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-10T00:48:48.888Z
Learning: Applies to **/*.md : Parse YAML frontmatter in markdown files for agent configuration

Applied to files:

• docs/agent-tips-tricks.md

📚 Learning: 2025-12-10T00:48:48.888Z

Learnt from: CR
Repo: johnlindquist/mdflow PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-10T00:48:48.888Z
Learning: Applies to **/*.md : Implement imports in markdown files using syntax: basic (`@./path.md`), globs (`@./src/**/*.ts`), line ranges (`@./file.ts:10-50`), symbols (`@./file.ts#InterfaceName`), commands (`` !`cmd` ``), and URLs (`https://example.com/file.md`)

Applied to files:

• docs/agent-tips-tricks.md

🪛 LanguageTool

docs/agent-tips-tricks.md

[style] ~359-~359: Consider using a different verb for a more formal wording.
Context: ...ration enables the agent to explore and fix issues autonomously. Usage: ```bas...

(FIX_RESOLVE)

🔇 Additional comments (2)

docs/agent-tips-tricks.md (2)

422-450: Comprehensive and well-organized documentation.

The tips are clearly structured with concrete examples, rationale, and usage patterns. The quick reference table effectively summarizes feature syntax, and the best practices list provides actionable guidance for developers new to advanced mdflow patterns. The progression from simple patterns (Tip 1) to orchestration (Tip 10) naturally builds complexity.

---

299-299: URL imports with template variable substitution are not supported in mdflow.

The syntax @{{ _api_base }}/openapi.json will not work as intended. The import system expands imports before template variable substitution occurs. The URL pattern matcher expects literal URLs starting with https:// or http://, so @{{ _api_base }}/openapi.json won't be recognized as an import. The template substitution only happens afterward, leaving the unprocessed @https://... in the final prompt rather than fetching it.

Use a static URL import instead: @https://api.example.com/openapi.json, or import a file path that contains the API base URL and reference it through a symbol or file import.

Likely an incorrect or invalid review comment.

[cds-amal]

Hey @johnlindquist , hopefully this is an appropriate place to put this.

How-to disable mcpServers for the agent's session

1. mcp-config needs to conform to a schema, {} wont work.
2. strict-mcp-config has to be true, otherwise it gets dropped in the command construction pipeline

---
model: sonnet
strict-mcp-config: true
mcp-config: '{"mcpServers": {}}'
$1: p
---

solve the halting problem!

[johnlindquist]

@cds-amal Thank you!!!