Alex' Gardenアレックスの庭

4 min read

add-skill

Skills in this vault live in one place: 7_Agent/skills/. Every agent-specific folder (.agents/skills/, .claude/skills/, future .codex/skills/, …) is a symlink that resolves there. New agents get a new symlink, not a new copy.

Why 7_Agent/skills/ and not .agents/skills/

Obsidian’s file explorer does not reliably render dot-prefixed folders, and Quartz (and globby in general) skips them by default. Keeping the real files under 7_Agent/skills/ makes them visible in the Obsidian sidebar, easy to edit inline, and trivially excludable from publishing (7_Agent/** is already in the Quartz ignore list). The dotfolder symlinks exist only because external tools (Claude Code, etc.) expect those paths.

Layout contract

7_Agent/
└── skills/                       # single source of truth — write here
    ├── add-skill/
    ├── audio-inbox/
    ├── consolidate/
    ├── crystallize/
    ├── log-question/
    ├── obsidian-cli/
    ├── obsidian-markdown/
    ├── process-inbox/
    ├── recent-changes/
    ├── reconcile/
    ├── reflect/
    ├── triage/
    ├── vault-tree/
    └── warmup/

.agents/
└── skills -> ../7_Agent/skills   # symlink

.claude/
└── skills -> ../.agents/skills   # symlink (chains through .agents)

Rules:

  • Write skill files directly under 7_Agent/skills/<name>/. Never use the symlinked paths (.agents/skills/..., .claude/skills/...) to create, move, or edit skill files. The symlinks are for reading by external tools only.
  • Never create a real directory at .agents/skills/ or .claude/skills/. They must stay symlinks.
  • When adding support for a new agent (Codex, Gemini, Cursor, etc.), create its folder (.codex/, .gemini/, …) and symlink its skills subfolder back to 7_Agent/skills/ (directly, not through another symlink). Same pattern, no duplication.

How to add a skill

  1. Pick a kebab-case name. It becomes the directory name and the name: frontmatter field.
  2. Create the skill directory under the real location: 
    mkdir -p 7_Agent/skills/<name>
  3. Write SKILL.md with the standard frontmatter: 
    ---
name: <name>
description: Use when … (trigger conditions, clear and specific).
---
 
# <name>
 
<body: when, inputs, procedure, output, edge cases>
  4. Verify it’s visible through every agent symlink: 
    ls .agents/skills/<name>/SKILL.md
ls .claude/skills/<name>/SKILL.md
    If either fails, the symlink is broken — fix it before adding more skills.
  5. Register it in AGENTS under the Skills section if it’s a vault-operational skill (Ingest/Query/Reconcile protocol or a supporting operation). Reference-only or shared-utility skills (like obsidian-markdown, vault-tree) can be listed separately.

How to add a new agent

When onboarding another AI agent’s folder (e.g., .gemini/):

mkdir -p .gemini
ln -s ../7_Agent/skills .gemini/skills

Point the symlink at ../7_Agent/skills directly — do not chain through .agents/skills. Do not copy skill directories into the new agent folder. The symlink is the whole integration.

Frontmatter requirements

Every SKILL.md must have:

  • name: — kebab-case, matches directory name.
  • description: — starts with “Use when …“. Trigger phrasing matters; this is what the agent sees when deciding whether to invoke.

Optional:

  • license: — if the skill is shared/portable.

Checklist

  • Directory created under 7_Agent/skills/<name>/ (the real path, not via a symlink)
  • SKILL.md exists with name + description frontmatter
  • Visible via .agents/skills/<name>/SKILL.md and .claude/skills/<name>/SKILL.md (symlinks resolve)
  • Listed in AGENTS if operationally relevant
  • No files created directly under .agents/skills/, .claude/skills/, or any other symlinked agent folder

iCloud caveat

The vault lives inside iCloud Drive. If you create a symlink at a path that iCloud thinks is about to conflict with a remote copy, macOS silently renames it (e.g., skills → skills 2). After creating or touching any agent symlink, verify with ls -la .agents/ and ls -la .claude/ that the name is exactly skills — not skills 2, not skills (conflicted). If it was renamed, mv it back.

Anti-patterns

  • Writing a skill via a symlinked path (.agents/skills/<name>/SKILL.md, .claude/skills/<name>/SKILL.md). It silently lands in 7_Agent/skills/<name>/, but the intent is invisible to future maintainers. Write to 7_Agent/skills/<name>/ explicitly.
  • Duplicating a skill into both 7_Agent/skills/ and an agent folder. The symlinks exist exactly to prevent this.
  • Turning .agents/skills or .claude/skills back into a real directory because “just this once”. Revert it — all agent folders must stay thin.

Graph View