Inside your wiki or vault¶
fitdocs works well on its own, but it was designed to live inside a larger markdown knowledge base, so your training sits next to your journal, your projects, and everything else you think about. Workout pages become ordinary pages in your wiki. You can link to them, search them, and query them together with the rest of your notes.
How it stays out of your way¶
- It only writes to its own folders:
workouts/,fit-archive/,history/,blocks/, and its hidden.cache/and.fitdocs/. Nothing else in your wiki is touched. - Your notes can point at fitdocs; fitdocs never points back. Link from your daily note to
[[2026-09-16-run-1132]]as much as you like. fitdocs never reads or links to your other pages.
Setup: five steps¶
Run these from the root of your wiki.
1. Install fitdocs (Install).
2. Make the wiki the data root.
Now any fitdocs command run from inside the wiki finds it.
3. Configure the inbox. Accept the default inbox/, or point at the folder where your sync app already drops files:
(Add [tiles] with enabled = false if you want no network access at all. See Privacy.)
4. Install the agent skill (next section).
5. First sync and check.
Agent skills¶
fitdocs includes agent skills: markdown instruction files in the open SKILL.md format that tell an LLM agent how to operate fitdocs correctly. They ship inside the package, so they always match the version you have installed.
| Skill | What it teaches your agent |
|---|---|
fitdocs-workouts |
Drain the inbox, run check, read the report, and know what to do about deferred, quarantined, or failed files. It also knows not to run regen unless asked, and to leave quarantined files to you. |
build-training-block |
Interview you about a training block, write the plan file, render it, add amendments, and settle ambiguous matches (Training blocks). |
Find them:
fitdocs skill # list packaged skills and where they're installed
fitdocs skill fitdocs-workouts # print one skill's folder and a copy command
Install: copy or symlink each skill's folder into your agent's skills directory, keeping the skill's own name. Each agent looks in a different place, so check your agent's documentation for its skills directory (for example .claude/skills/ in a Claude Code project).
# Symlink: picks up new versions automatically when you upgrade fitdocs
ln -s "$(fitdocs skill fitdocs-workouts | head -n1)" <skills-dir>/fitdocs-workouts
# Or copy (after an upgrade, delete the old copy and copy again)
cp -R "$(fitdocs skill fitdocs-workouts | head -n1)" <skills-dir>/fitdocs-workouts
Check: ask your agent to list its skills. fitdocs-workouts should appear. Each copied SKILL.md has a metadata.version showing which fitdocs release it came from.
Point your wiki's own instructions at fitdocs¶
If your wiki has its own root AGENTS.md or CLAUDE.md, a short pointer is enough. You don't need to copy the rules:
## Workouts (fitdocs)
Training data is generated by fitdocs. See `workouts/AGENTS.md`,
`fit-archive/AGENTS.md`, `history/AGENTS.md`, and `blocks/AGENTS.md` for what
it owns. Never edit generated content; the Notes and Workout sections of a
workout page, and the race-tag frontmatter keys, are the user's.
fitdocs keeps those four files up to date. It never touches your root instructions file.
If your wiki is in git¶
The generated pages and archive can make diffs noisy. You can mark them as generated in .gitattributes so git and GitHub collapse them:
workouts/*.md linguist-generated
fit-archive/* linguist-generated -diff
history/*.md linguist-generated
history/assets/* linguist-generated -diff
blocks/*.md linguist-generated
blocks/*/*.md linguist-generated
The heavy folders (fit-archive/, chart assets, .cache/) can also be left out of git entirely, since fitdocs regen can rebuild every page from the archive. Just make sure the archive itself is backed up somewhere.
Obsidian¶
Nothing special is needed. Open the vault, and workout pages show up with their charts, because they're standard image links. The frontmatter works with Dataview and Bases. Wikilinks in effort_event show up as normal links.