organize-skills - SKILL.md Agent Skill

name: organize-skills description: Use when creating, reorganizing, or maintaining the skills/ directory. Covers the shared skill layout conventions, directory structure, SKILL.md format, symlink architecture, and how to add or restructure skills so both Claude Code and Gemini CLI discover them.

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
    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: "Read references/advanced.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

Rules:

Lowercase kebab-case: dev-testing, build-images
Prefix is the category, suffix is the topic: <category>-<topic>
Meta/standalone skills that don't belong to a category skip the prefix
Name after the action or domain: what the skill helps you do
Avoid generic names like utils or helpers

Current categories:

meta-* -- skills about skills (find, create, organize)
dev-* -- daily development (toolchain, testing, debugging, diagnostics)
build-* -- building VM images and guest binaries
release-* -- release process, CI, documentation site
frontend-* -- frontend development (reserved)