# Organize Skills > 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. - Skill: `tomevault-io/organize-skills` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/organize-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/organize-skills/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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.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 ```markdown --- 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: 1. **Metadata** (name + description) -- always in context (~100 words) 2. **SKILL.md body** -- loaded when skill triggers (<500 lines ideal) 3. **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 1. `mkdir skills/` 2. Write `skills//SKILL.md` with frontmatter + instructions 3. It's immediately available to both CLIs (live reload, no restart) For community skills from `npx skills find` or skills.sh: ```bash curl -sL https://raw.githubusercontent.com///main/skills//SKILL.md \ -o skills//SKILL.md ``` ## Removing a skill `rm -rf skills/` -- 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: `-` - 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) --- > Source: [google/capsem](https://github.com/google/capsem) — distributed by [TomeVault](https://tomevault.io).