Skip to content

docs: document session-command skills and code-location guidance (EN + pt-BR) - #8

Open
shiyao821 wants to merge 2 commits into
lucasrosati:mainfrom
shiyao821:chore/update-readme-on-skills-and-code-location
Open

docs: document session-command skills and code-location guidance (EN + pt-BR)#8
shiyao821 wants to merge 2 commits into
lucasrosati:mainfrom
shiyao821:chore/update-readme-on-skills-and-code-location

Conversation

@shiyao821

@shiyao821 shiyao821 commented Jul 10, 2026

Copy link
Copy Markdown

I mostly added these as I had some misconceptions while reading the README.md. Making these points explicit I think will help the next person.

What

Updates the setup guide (both English and Portuguese READMEs) with three additions:

  • ⚠️ "Keep code out of the vault" warning — clarifies the vault holds notes only, and that code repos must live elsewhere so Obsidian doesn't choke on node_modules/, build output, etc.
  • New setup step: turning /save + /resume into global skills — explains implementing the session commands as skills under ~/.claude/skills/ so they fire reliably in any project, instead of repeating the prose in every CLAUDE.md.
  • "Unknown Command" troubleshooting entry — explains the headless-CLI-vs-skill distinction when graphify . errors with unknown command '.'.

Plus a minor note that graph.json / GRAPH_REPORT.md are worth keeping versioned for the team.

Why

The skills-based approach is more reliable than CLAUDE.md prose, and new users were putting code repos inside the vault (killing Obsidian performance). The two changes address the most common setup mistakes.

Notes

README.pt-BR.md mirrors README.md, adapted to the pt-BR conventions already in that file (/retomar, /salvar, projeto/).
Docs-only change — no code affected.

@lucasrosati

Copy link
Copy Markdown
Owner

Great additions — the vault warning and the skills section address real confusion points (see #5).

Two things before merge:

  1. The "Unknown Command" troubleshooting entry only made it into README.pt-BR.md —
    the English README.md diff doesn't include it. Could you mirror it there?

  2. In that troubleshooting block, --mode deep is listed among the skill-form flags,
    but we removed that flag in the recent CLI-accuracy PR (semantic extraction now runs
    automatically when an LLM API key is set). Please drop it from the example to keep
    the guide consistent.

Happy to merge once those two are in.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants