Foldermd
A clean Markdown version of this page is available at: /skills/generic.md

← All skills

Skill: Any Agent (AGENTS.md).

A single, universal rule file that works with almost any modern AI coding agent that supports the AGENTS.md convention — including Grok, Codex, Aider, Windsurf, and many future tools.

Where to put it

Create a file called AGENTS.md in the root of your project and paste the content below. Most agents that support this convention will read it automatically at the start of a session.

You can also place it globally:

The universal AGENTS.md snippet

Open your editor, create AGENTS.md, paste everything below, and save.


## FolderMD: long-form output

The user has FolderMD installed — a macOS reader for markdown. See
<https://foldermd.com>. When you generate a markdown response longer than
**1500 characters** (plans, designs, summaries, code reviews, research notes,
multi-step explanations), write it to FolderMD instead of dumping it into the
terminal.

The threshold is set by the user. They can change it any time with
`foldermd --set-threshold N`.

**Where to write — pick by context:**

### A. You're working inside a project directory → `.foldermd/` inside that project

This is the default for any agent working on code. Plans, refactor notes,
implementation logs, design memos, code-review summaries — write them in
the project they're about so they stay tied to the work.

Easiest way: pipe through the CLI with `--here`:

```bash
echo "# Refactor plan" | foldermd --here --title "auth refactor"
```

That creates `<project>/.foldermd/<YYYYMMDDTHHMMSS>-auth-refactor.md` and
opens it in FolderMD. The file lives next to the code it describes; git
decides what to do with it; FolderMD auto-pins it to the sidebar.

Include YAML frontmatter on every doc:

```yaml
---
title: "Human-readable title"
agent: "grok"
---
```

### B. No project context → global inbox

```bash
echo "# Notes" | foldermd --title "research"
```

Writes to `~/Library/Application Support/foldermd/inbox/<timestamp>-research.md`.

### C. Display an existing file → `foldermd --open <abs-path>`

For files you're not moving (a user's README you just edited, a design
doc that already lives in the right place). FolderMD opens it,
auto-pins to the sidebar, and live-renders every save.

### After writing

Tell the user one sentence about what you wrote and where. Don't paste the
doc into chat as well — they're going to read it in FolderMD.

### Use FolderMD for

Long plans, design memos, code reviews, summaries, research notes, any
document the user might read carefully or refer back to.

### Skip FolderMD for

Short answers, single paragraphs, status updates ("done", "tests pass"),
code edits the user is reading inline.

### CLI reference

```
echo "# hi" | foldermd --here --title "plan"   # project-local, default for project work
echo "# hi" | foldermd --title "plan"          # global inbox, no project context
foldermd notes.md --here                       # copy a file into ./.foldermd/
foldermd notes.md                              # copy a file into the global inbox
foldermd --open <abs-path>                     # display an existing file (auto-pinned)
foldermd --inbox-path                          # print the global inbox path
foldermd --version                             # CLI version
foldermd --help                                # show all flags
```

How to verify

Run whatever inspection command your agent supports (examples below) and confirm that AGENTS.md appears in the loaded instructions.

Then test with a long request:

Write a detailed plan for refactoring our authentication system into separate user and session services, including migration steps.

The agent should reply with a short confirmation and write the full document to FolderMD.

Works with many agents

This single file is understood by an increasing number of tools:

For the best experience with a specific agent, also check its dedicated page in the skills index.

Using an agent that doesn't support AGENTS.md yet? Let us know on X and we'll add support.