agentleFS
AxectAxect/skills/research-portal/SKILL.md

research-portal

Skill4 starsChanged 20 days agoMITView on GitHub

Build and manage a local MkDocs Material "research portal" over a folder of Typora/markdown research notes (e.g. ~/notes or a Dropbox-synced folder), keeping the original .md files untouched. Use this whenever the user wants to collect, browse, organize, or curate a folder of dated markdown notes into a searchable navigable site; wants a lighter local alternative to Obsidian / Notion / Outline / Logseq for their own notes; needs perfect LaTeX/math rendering in a notes site; wants notes grouped by project in a sidebar; or wants to tag/rename notes by project without breaking image links. Trigger even if they don't say "MkDocs" or "portal" but describe wanting to "정리해서 모아 보기", make a personal wiki, or render math from their note folder.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Only three helper files land in the notes folder, all regenerable/deletable: index.md (home), SUMMARY.md (sidebar nav), …

    line 38
  2. Very specific:

    All commands run from the portal dir with uv.

    line 49
  3. Distinctive:

    Ask for the notes folder if not given.

    line 55
  4. Distinctive:

    Run it in the background so you can keep working.

    line 75
  5. Very specific:

    After scaffold/build: uv run mkdocs build exits 0 (the red "MkDocs 2.0" notice from Material is harmless).

    line 113
  6. Very specific:

    After tagging: the script's own link verification must report "all asset refs resolve OK".

    line 116

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Research Portal

Turn a folder of dated markdown notes into a local, searchable MkDocs Material site with project-grouped navigation and full LaTeX rendering, without ever modifying the source notes. The site is read/browse oriented; authoring stays in the user's existing editor (Typora), so the .md files remain the canonical source.

When this fits (and when it doesn't)

This is the right tool when notes are flat markdown files in a folder (often Dropbox-synced), named by date like YYYYMMDD[_PROJECT].md, with images in sibling <stem>.assets/ folders. It deliberately avoids database-backed wikis (Outline needs Postgres/Redis/SSO; Notion is a SaaS DB) because those divorce content from the user's files and break the Typora workflow. If the user instead wants backlink/graph visualization, mention Quartz as a complement; this skill does not do graphs.

Design choices (read references/design.md for the why)

  • docs_dir points straight at the notes folder. The site serves .md, .assets/ images, and PDFs in place; originals are never touched.
  • Only three helper files land in the notes folder, all regenerable/deletable: index.md (home), SUMMARY.md (sidebar nav), javascripts/mathjax.js.
  • Math: pymdownx.arithmatex (generic) protects inline $...$ from markdown, and MathJax 3 also scans raw $$...$$ as a fallback because arithmatex's block processor does not descend into list items (Typora notes often nest display math under bullets). This combination renders both reliably.
  • Broken symlinks in the source abort an mkdocs build, so the scaffolder auto-excludes any first-level subtree that contains dangling links.

Workflow

All commands run from the portal dir with uv. Scripts are bundled in scripts/; the scaffolder copies gen_index.py and tag_note.py into the portal dir so the portal is self-contained.

1. Scaffold

Ask for the notes folder if not given. Then:

python <skill>/scripts/scaffold.py \
  --notes-dir ~/notes \
  --portal-dir ~/research-portal \
  --name "Research Portal" --lang ko --port 8123

This writes mkdocs.yml, copies the helper scripts, writes the MathJax config, detects broken-symlink subtrees to exclude, then creates the uv venv, installs mkdocs-material + mkdocs-literate-nav, and builds the nav. Pass --no-install to only generate files (it then prints the uv commands to run).

2. Serve

cd ~/research-portal && uv run mkdocs serve -a 127.0.0.1:8123

Run it in the background so you can keep working; it live-reloads when notes or config change. After installing a new plugin, restart serve (a running process won't see newly installed packages). Tell the user the URL and suggest a hard refresh (Ctrl+Shift+R) after JS/config changes.

3. Regenerate nav after adding/removing notes

cd ~/research-portal && uv run python gen_index.py --title "Research Portal"

gen_index.py parses YYYYMMDD[_PROJECT[_extra]].md, groups by project (most notes first, untagged "Daily" last), labels each entry by date, and writes index.md + SUMMARY.md. It reads the notes dir from docs_dir in mkdocs.yml.

4. Tag / rename notes by project

Untagged date-only notes show up under "Daily". To file them under a project, first read enough of each note to classify it (section headers grep -E '^#{2,3} ' are a fast topic fingerprint). For genuinely multi-project notes, ask the user rather than guessing. Then:

cd ~/research-portal
# preview first
uv run python tag_note.py --project ProjectA 20240115 20240116 --dry-run
# apply
uv run python tag_note.py --project ProjectA 20240115 20240116

tag_note.py renames <stem>.md, the <stem>.assets/ folder, and a matching <stem>.pdf, and rewrites every <stem>.assets reference across ALL notes (image references can be cross-file). It then verifies all *.assets references resolve. Use --rename OLD NEW for an explicit single rename (e.g. re-tagging an already-suffixed note). Always run gen_index.py afterward to refresh the nav.

Verify before reporting done

  • After scaffold/build: uv run mkdocs build exits 0 (the red "MkDocs 2.0" notice from Material is harmless). Confirm math by grepping the built page for class="arithmatex" and that *.assets/ images copied into site/.
  • After tagging: the script's own link verification must report "all asset refs resolve OK"; also confirm no date-only notes remain if the intent was to clear "Daily" (ls <notes> | grep -E '^[0-9]{8}\.md$').

Scripts and references

  • scripts/scaffold.py — create/refresh the portal project and uv env
  • scripts/gen_index.py — regenerate index.md + SUMMARY.md
  • scripts/tag_note.py — safe project tagging/renaming with link repair
  • references/design.md — rationale for the math config, file layout, and the Outline/Obsidian comparison; read it if the user questions a design decision or wants to adapt the setup (different filename scheme, KaTeX, hosting, etc.).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.