Obsidian PARA Skills

Agent Skills for working in a PARA-organized Obsidian vault. Written to the Agent Skills specification, so they run in any skills-compatible agent — Claude Code, Codex, OpenCode.

This is a fork of kepano/obsidian-skills by Steph Ango, which supplies five skills for Obsidian's file formats and CLI. Those five are included here unmodified. What this fork adds is a para-* suite for the layer above the file formats: how an actual vault is organized, and how an agent should behave inside one.

What's different about these skills

Most vault automation breaks the moment it meets a real vault, because it assumes a structure the vault doesn't have. The para-* skills are built around three ideas that came out of using them daily rather than designing them up front.

One file holds everything vault-specific. The skills teach generic PARA and Obsidian-plugin patterns. Every value particular to one vault — folder names, tag vocabulary, plugin settings, ports, secret references — lives in a single file, skills/para-vault/references/VAULT-CONFIG.md. Adapting the whole suite to a different vault means editing that one file. The skills themselves stay untouched, which is also what makes upstream merges clean.

A property, not a folder, is ground truth. PARA membership is the para frontmatter value, not where the file happens to sit. Folders drift; notes get dragged around; index views filter on the property. Skills that trust the path get this wrong constantly.

Documented failure modes, not just capabilities. Each skill carries the traps that actually bit — a GOTCHAS.md where one exists, and inline warnings where it matters. A worked example: this vault runs the Tasks plugin with no global filter, so every - [ ] checkbox in the vault is a live task, and an agent writing a casual checklist silently creates real ones. That is the kind of thing a generic skill never warns you about, and the kind of thing that costs an afternoon.

Skills

PARA suite

Added by this fork.

Upstream skills

Included byte-identical from kepano/obsidian-skills, forked at a1dc48e. © Steph Ango, MIT.

Installation

Claude Code marketplace

/plugin marketplace add https://github.com/mriechers/obsidian-PARA-skills
/plugin install obsidian@obsidian-para-skills

npx skills

npx skills add https://github.com/mriechers/obsidian-PARA-skills.git

Installing individual skills rather than the whole pack? You must also install para-vault — every other para-* skill reads its VAULT-CONFIG.md.

Manually

Claude Code — copy the repo contents into a .claude/ folder at the root of your vault (or whichever directory you point Claude Code at). See the Agent Skills docs.

Codex — copy skills/ into your Codex skills path, typically ~/.codex/skills.

OpenCode — clone the whole repo into ~/.opencode/skills/:

git clone https://github.com/mriechers/obsidian-PARA-skills.git ~/.opencode/skills/obsidian-PARA-skills

Clone the full repo, not just the inner skills/ folder — OpenCode discovers SKILL.md files at ~/.opencode/skills/<repo>/skills/<skill-name>/SKILL.md. Skills become available after a restart.

Using these on your own vault

VAULT-CONFIG.md currently describes one real vault, which makes it a worked example rather than a blank template. To adapt it:

1. Replace §1–2 with your vault's path and PARA folder names.
2. Rewrite §3 to your frontmatter vocabulary — especially the para property values and your anchor tag.
3. Update §4–7 for the plugins you actually run. Delete the sections for plugins you don't; the skills degrade gracefully when a section is absent.
4. §8 holds a secret reference (a 1Password op:// path), never a secret. Keep it that way.

Nothing outside that file needs to change.

Upstream sync

git remote add upstream https://github.com/kepano/obsidian-skills.git   # one-time
git fetch upstream
git merge upstream/main

The five upstream skill directories are kept byte-identical, so the expected conflict surface is README.md and .claude-plugin/ only. Resolve by keeping this fork's packaging and taking upstream's skill changes wholesale.

Development

Run tests/validate.sh before committing — static validation of frontmatter, links, packaging, and forbidden content.

License

MIT. Upstream skills © Steph Ango (kepano); the para-* skills © Mark Riechers. See LICENSE.

{
  "name": "obsidian-para-skills",
  "owner": {
    "name": "Mark Riechers",
    "url": "https://github.com/mriechers"
  },
  "plugins": [
    {
      "name": "obsidian",
      "source": "./",
      "description": "Claude Skills for Obsidian — upstream skills by Steph Ango (kepano) plus PARA vault workflow skills",
      "version": "2.0.2"
    }
  ]
}