Apothem vs raw Cursor config
Hand-maintaining Cursor's MDC rules under .cursor/rules/ versus rendering them from Apothem's shared profile.
Cursor reads rules in MDC format under .cursor/rules/. The MDC format requires
frontmatter fields — description, globs, and alwaysApply. Apothem's cursor
adapter renders one .mdc rules file from the shared profile. This page
contrasts hand-maintaining that config against managing it with Apothem.
Effort comparison
| Task | Raw hand-config | Apothem-managed |
|---|---|---|
| Author rules | Hand-write each .mdc file under .cursor/rules/ | Rendered from the shared corpus |
| Write MDC frontmatter | Hand-author description / globs / alwaysApply per file | Generated by the adapter |
| Keep one rule format | Hand-pick between MDC rules and a single .cursorrules file | The adapter writes one MDC file, .cursor/rules/apothem-rules.mdc, and no .cursorrules |
| Keep rules aligned with other harnesses | Manual, per tool | Automatic on apothem update |
| Share reusable skills and commands | Hand-copy each skill folder into ~/.agents/skills/ and keep the copies current | Written to ~/.agents/skills/ by the adapter, one copy for every project, and refreshed on apothem update |
| Verify the config is correct | Manual inspection | apothem verify --harness cursor --project <path> |
What Apothem manages
The cursor adapter renders the shared rules into one .mdc file,
<project>/.cursor/rules/apothem-rules.mdc, generating the required MDC
frontmatter (description, globs, alwaysApply). The adapter writes only the
directory-based MDC format Cursor reads; it does not write a single-file
.cursorrules. It also writes the skills, and the commands wrapped as skills,
to ~/.agents/skills/, and the rules and templates those skills cite to
~/.config/apothem/, both in your home directory.
Cursor documents hooks in hooks.json files and through its plugin format. The
adapter builds no plugin; it adds one sessionStart entry to the project's
.cursor/hooks.json, which loads the session bootstrap, and leaves your own
entries as they are. It registers no tool-call guard, so guardrail intent lives
in the rule prose.
Migration path
- Run
apothem profile initto create the shared profile if you have not yet. - Move the rules from your existing
.cursor/rules/(and any.cursorrules) into the shared corpus. - Run
apothem install --harness cursor --project <path>to renderapothem-rules.mdcwith correct MDC frontmatter. - Run
apothem verify --harness cursor --project <path>to confirm the config landed. - Use
apothem update --harness cursor --project <path>for every later change.