meta-organize-skills

Organize Skills

This project uses a shared skills/ directory at the repo root. Both Claude Code and Gemini CLI discover skills from it via symlinks -- one set of files, two consumers.

Directory structure

skills/                          Canonical location (checked into git)
  <skill-name>/
    SKILL.md                     Required -- the skill itself
    references/                  Optional -- large docs loaded on demand
    <skill-name>/scripts/        Optional -- executable helpers
    assets/                      Optional -- templates, icons, etc.

.claude/skills -> ../skills      Claude Code symlink
.agents/skills -> ../skills      Gemini CLI symlink

Rules:

One skill per directory. The directory name is the skill identifier.
Every skill directory must contain a SKILL.md file. No other naming is discovered.
Never put files directly in .claude/skills/ or .agents/skills/ -- those are symlinks to skills/.
Bundled resources (references, scripts, assets) go in subdirectories of the skill directory.

SKILL.md format

---
name: skill-name
description: When to trigger and what it does. Be specific and slightly pushy -- Claude undertriggers skills, so include concrete contexts. All "when to use" info goes in the description, not the body.
---

# Skill Title

Body: instructions the agent follows when the skill triggers.
Keep under 500 lines. For larger skills, use references/ for overflow.

Required frontmatter fields:

name -- skill identifier (matches directory name)
description -- triggering text. This is what Claude sees in its skill list to decide whether to load the skill. Include both what the skill does AND specific phrases/contexts that should trigger it.

Optional frontmatter:

user-invocable: true -- lets users invoke with /skill-name
allowed-tools: Read, Grep, Bash -- restrict which tools the skill can use
context: fork -- run in a subagent instead of main context

Progressive disclosure

Skills load in three tiers:

Metadata (name + description) -- always in context (~100 words)
SKILL.md body -- loaded when skill triggers (<500 lines ideal)
Bundled resources -- loaded on demand from references/ (unlimited size)

Keep SKILL.md lean. If approaching 500 lines, split detail into references/ files and add clear pointers naming each one, for example: Read references/.md for the full configuration reference.

Adding a skill

mkdir skills/<name>
Write skills/<name>/SKILL.md with frontmatter + instructions
It's immediately available to both CLIs (live reload, no restart)

For community skills from npx skills find or skills.sh:

curl -sL https://raw.githubusercontent.com/<owner>/<repo>/main/skills/<name>/SKILL.md \
  -o skills/<name>/SKILL.md

Removing a skill

rm -rf skills/<name> -- both CLIs stop seeing it immediately.

When to split vs. bundle

Split into separate skill directories when the skills have different trigger conditions. A debugging skill and a release skill should be separate -- they trigger on different user intents.
Bundle into one skill with references/ when the content is one domain with multiple sub-topics. A frontend skill that covers Svelte patterns, chart library, and CSS conventions is one skill with optional reference files.

Naming conventions

Skills are flat (one level under skills/). Nested subdirectories are NOT discovered by Claude Code or Gemini CLI. Use prefix-based grouping to organize related skills into logical categories:

skills/
  dev-testing/SKILL.md          dev category -- testing
  dev-debugging/SKILL.md        dev category -- debugging
  dev-diagnostics/SKILL.md      dev category -- in-VM diagnostics
  build-images/SKILL.md         build category -- capsem-builder
  build-initrd/SKILL.md         build category -- initrd repack
  release-process/SKILL.md      release category
  release-docs/SKILL.md         release category -- site docs
  find-skills/SKILL.md          meta (no prefix needed)
  skill-creation/SKILL.md       meta
  organize-skills/SKILL.md      meta