2026-09-12 · Markdown tools

Marginal 2026: A Markdown Editor Built for Coding Agents

Here is a sentence that would have been nonsense in 2020: the most consequential prose most developers write now is not the code, it is the Markdown that tells an agent how to write the code. A CLAUDE.md at the root of a repository changes behavior on every future session. A SKILL.md with a malformed YAML front matter block silently stops loading. A rule file scoped to one subdirectory quietly overrides a rule you thought was global.

For most of the last year the tooling for that authoring work has been whatever editor you already had open — a general-purpose code editor, a note-taking app, or vim in a terminal tab. On September 2, 2026, Kunihiro Ishiguro published a blog post titled Markdown Editors Weren't Built for Coding Agents, So I Made One and shipped Marginal, a native Markdown editor whose headline feature is finding the files your coding agent actually reads. This article looks at what it does, where it fits, and — because the honest answer matters more than the launch copy — where it does not.

The problem Marginal is solving

The author's own description of the problem is more useful than any feature list. He writes that he uses coding agents heavily every day, mainly Claude Code, and has them write dev plans, run security audits, and generate BDD test cases. Each of those artifacts lands in Markdown. He also periodically maintains his CLAUDE.md and installs other engineers' skills. The result, in his words: an overwhelming number of Markdown documents, sometimes more than 100, scattered across different subdirectories.

Then the harder part. He had lost track of which skills were currently available, which sub-agents were installed, and which rules were in effect. Some of those files are project-local; some are shared across an account on a specific machine. He also uses other agents like Codex and OpenCode, and each of them searches different paths for its configuration.

The specific pain that made him build the tool is sharper still: SKILL.md files use a special Markdown format with YAML front matter containing mandatory fields such as name and description. He wanted an editor that understood that structure and highlighted it properly. He went looking, and, in his account, could not find anything that met the requirements.

That framing is worth pausing on, because it is not a complaint about Markdown editors being bad. It is a claim about a category mismatch: today's Markdown editors work well for note-taking and for getting things done, and neither of those is the same job as maintaining an agent's configuration surface.

What it actually does

Marginal's first feature is the one that motivated the project. You pick your coding agent — Claude Code is the default — and the sidebar lists every Markdown file that agent will read for the open folder, along with its skills, rules, sub-agents, and commands. Each entry shows the name from the file's front matter when it has one, its description as a second line, and a badge indicating provenance.

Entries are ordered project first, then local, then user — which happens to be the same precedence order agents resolve them in, so reading the list top to bottom approximates reading the effective configuration. The sections (CLAUDE.md, RULES, SKILLS, AGENTS, COMMANDS) start collapsed and only appear when they have entries.

The agent table

Marginal knows the layout of six agents. The mapping is not cosmetic — each of these tools genuinely names its instruction file something different, which is the root cause of the confusion the article opens with.

Switching the agent changes what is listed, not what is on disk. A folder carrying both a CLAUDE.md and an AGENTS.md shows one or the other depending on which agent you selected — which is a genuinely useful way to see, with your own eyes, why the same repository behaves differently under two different agents.

Not every agent file is Markdown

A detail worth noting for anyone who has been confused by a config file that would not open: Cursor rules are .mdc, Codex sub-agents and execution rules are .toml and .rules, and Qwen Code still reads its older .toml commands. Marginal lists them because the agent reads them, and opens them in the editor as plain text. The tool follows the agent's reality rather than enforcing a purist definition of Markdown.

Everything else in the app

• Subfolder discovery, opt-in. Turn on "List files in subfolders" and the list shows every Markdown file under the selected directory. The filter box matches on partial paths including / to match a directory, so you can type /api and see only what lives under it.
• Inline AI editing. Select text, press Cmd+K, describe the change. The rewrite streams as an inline diff that you accept or reject as a single undo step. It runs on your own API key with a choice of Anthropic, OpenAI, Google, xAI, or Alibaba Cloud.
• A terminal panel in the app. Cmd+J opens a terminal below the editor so you can run claude or codex without leaving the window. When the agent writes to a file you have open, Marginal notices and offers to reload it, and a newly saved skill appears in the skills section without reopening the folder.
• Reading mode and export. Double-clicking a Markdown file in Finder opens it in reading mode, which hides the editor chrome and shows only the preview. From there you can export directly to PDF or HTML. Escape returns you to editing.
• Emacs and Vim modes. The editing mode can be set to Default, Emacs, or Vim, with the active mode shown in the status bar. The author is candid about his own preference — he needs Ctrl+S to search within the file and land on the third occurrence of a word.
• Ten themes. Five light/dark pairs: Marginal, GitHub, Solarized, Zenburn, and Dracula. A theme is a single JSON file, so you can install your own and Marginal loads it without a restart.

The part most launch posts would leave out

Engagement on this one has been small. The blog post was submitted to Hacker News on September 3, 2026 and, as of this writing, sits at 2 points with no comments. That is not a knock on the software — plenty of useful tools launch quietly, and a native app with a subscription is a harder sell to a forum that rewards free and self-hosted. But it does mean you should evaluate this on its own merits rather than on a wave of enthusiasm, so here are the caveats that come with it.

• It is version 1.0. The site advertises 1.0 explicitly. The design is coherent and the scope is disciplined, but there is no long track record yet and no large community of users filing the edge cases for you.
• Editing is behind a subscription. $10 a month or $96 a year. The read-side is genuinely free and permanent — opening files and folders, reading, live preview, print, PDF export, HTML export, and themes all work signed out. If editing lapses, the app turns read-only, and a document you changed while licensed can still be saved. The AI features are described as never gated, which is a sensible split: you pay for the app, not for access to your own API key.
• It is an editor, not a knowledge base. No graph view, no plugin marketplace, no sync service, no backlinks. If your Markdown is a vault of linked notes, this is not the tool that replaces Obsidian and it is not trying to be.
• Six agents is a real limit in a fast-moving category. The author explicitly invites users to report agents Marginal does not look at yet, and frames each addition as a row in a table — but if your team standardized on something outside those six, the headline feature does not apply to you today.
• Environment inheritance has a genuine sharp edge. The documentation notes that if an agent has an environment variable that relocates its config folder — CLAUDE_CONFIG_DIR or CODEX_HOME — Marginal honors it only when it is set in the environment Marginal was started from. An app launched from the Dock or the Start menu sees a different environment than one launched from a terminal. If your config lives somewhere unusual, start it from the shell.

That last point is the kind of thing worth knowing before you decide the feature is broken. It is documented, which is to the author's credit, but it will bite someone.

Why this category is suddenly real

The reason Marginal is interesting is not the editor. It is what the editor implies about where Markdown sits in a developer's workflow now.

Markdown has been the lingua franca of notes, README files, and static site generators for years. What changed is that Markdown became the control plane for software that acts. A skill file is not documentation about capabilities, it is the capability. A rules file is not a style guide, it is enforcement. When you edit one of those files you are programming an agent in prose, and the feedback loop is the agent's next session.

Once you accept that framing, the requirements change in ways a note-taking editor does not satisfy. You need to see which files are in effect and which are shadowed. You need front matter treated as structure, not as text that happens to start with ---. You need the terminal in the same window as the file, because the edit and the test are one action. None of that is exotic, but all of it is specific, and specific requirements are what justify a purpose-built tool.

Two Markdown-to-rich-text examples

Here is where the agent-authoring world meets the publishing world, which is the seam this site lives on. Suppose you have just written a skill file and you want to share the pattern with your team in a LinkedIn post or a Medium article. The Markdown is correct. The paste is where it breaks.

Take a small skill definition with front matter, a heading, and a task list:

---
name: changelog-writer
description: Turns merged PR titles into a dated changelog entry.
---

# Changelog Writer

## Steps
- [x] Read the merge log for the target window
- [x] Group entries by area
- [ ] Flag breaking changes for review

Run it after every release tag.

Pasted raw into a rich-text editor, the front matter can survive as a visible fence, the heading can flatten into bold body text, and the task list can degrade into a stack of literal - [x] lines. Second example, the one people get wrong most often — a short post that includes a config snippet and a table:

# We standardized our agent config on Markdown

One instruction file, one skills folder, no tribal knowledge.

| Agent | Instruction file |
| - | - |
| Claude Code | CLAUDE.md |
| Codex | AGENTS.md |

If a rule is not in the repo, it does not exist.

Both of those convert through md2rich entirely client-side — the site is a pure front-end tool, so nothing you paste ever leaves your browser. That property is not incidental in an agent workflow. The skills and rules you write are frequently the most internal prose your team produces: they describe how you handle customer data, what you must never touch, which systems require approval. A conversion step that uploads your draft to a server to format it is a worse trade than one that does not, and it is a strange thing to accept from a tool whose whole premise is that your files stay on your disk.

Where the two jobs separate

Marginal edits the Markdown that configures agents. You give it a folder; it finds the instruction file, the skills, the rules, and the commands that are actually in effect for the agent you selected. Its job is orientation — telling you what your agent will read before it reads it.

md2rich converts the Markdown you wrote for humans. You give it a finished draft; it gives you rich text you paste into LinkedIn, X Articles, Medium, or Notion. Its job is fidelity — making sure the platform does not destroy your structure on the way in.

Put another way: one is an authoring surface for machine-facing prose, the other is a conversion step for human-facing prose. They touch the same file format at two completely different moments, and neither one substitutes for the other. A team that writes a lot of agent configuration and also publishes about it will end up with both, and the reason is not upsell — it is that the two problems live at opposite ends of the document's life.

Bottom line

If you maintain agent configuration files for six or more projects and you have ever been unsure which SKILL.md was actually loading, Marginal addresses a real problem that no general-purpose editor addresses, and $10 a month is a fair price for seeing your effective configuration in one list. The 14-day trial needs no card, so the honest recommendation is to point it at the messiest repository you have and see whether it tells you something you did not know. If it does, the subscription is easy to justify. If your config is one CLAUDE.md and three skills, you already know what is in effect and you can skip it.

And when you turn that configuration work into a post — a migration write-up, a skill pattern, a postmortem — remember that the last mile is a separate problem. Convert it with md2rich before you paste it into LinkedIn, X Articles, Medium, or Notion. The Markdown stays on your machine the whole way through, which is the same promise a good native editor makes about your files.