Compose-MD

Appearance

How It Works ​

Prompt files are gitignored ​

AGENTS.md, SKILL.md, CLAUDE.md files etc are .gitignored

When you run compose apply <approach-name> the existing prompt files are removed and new ones are created.

Prompts are included to let your agent know not to modify the prompts directly ​

compose init adds these two fragments to your fragment library and wires them into the default approach:

  • @docs-workflow — starting/docs-workflow.md, included in the root output file
  • @compose-docs-skill — starting/compose-docs-skill.md, wired to .agents/skills/compose-docs/SKILL.md

@docs-workflow ​

md
# This project uses compose-md

The coding agent prompts (AGENTS.md, CLAUDE.md, SKILL.md etc) in this project are .gitignored. Do not edit them directly. 

Instead, edit the files in $PROJECT_DOCS

Invoke the /compose-docs skill to assist.

If your memory system would normally have you write something durable directly into one of these files, write it into the corresponding fragment in $PROJECT_DOCS instead, then run `compose apply` to regenerate the file.

@compose-docs-skill ​

md
---
name: compose-docs
description: Edit and regenerate this project's agent instruction files (AGENTS.md, CLAUDE.md, SKILL.md, etc.), which are generated by compose-md from fragments and approaches. Use this whenever you would normally create or edit agent instruction files, including updating your memory.
---

# compose-docs

This project's coding-agent instruction files (AGENTS.md, CLAUDE.md, SKILL.md, etc.) are generated by compose-md and are gitignored. Do not edit them directly — your changes will be overwritten the next time `compose apply` runs.

## Where the real content lives

- **Fragments** — `.md` files anywhere under `$PROJECT_DOCS/` (except `_approaches/`), each with a `name:` field in its frontmatter.
- **Approaches** — `.yaml` files in `$PROJECT_DOCS/_approaches/`. Each approach maps an output path (e.g. `AGENTS.md`) to a list of `@fragment-name` references and/or inline literal text (YAML block scalars, e.g. `- |`, work for multiline bespoke content like frontmatter headers).

## Workflow

1. Find the fragment behind the content you want to change — search `$PROJECT_DOCS/` for the relevant `name:` frontmatter, or look up the output path in the active approach's YAML.
2. Edit the fragment's markdown content.
3. Run `compose apply <approach>` to regenerate the output files from the fragments.
4. To add a new generated file, add an entry under `outputs:` in the approach YAML.
5. If your memory mechanism would normally write directly into AGENTS.md, CLAUDE.md, or a SKILL.md (e.g. to persist something durable you've learned), write it into the corresponding fragment instead, then run `compose apply`. Never write memory straight into a generated file — it will be overwritten.

Never hand-edit a generated file — always change the source fragment (or approach YAML) and re-run `compose apply`.

This should keep the agent from directly modifying prompt files, and instead be updating the fragment pool.