# Skill Manager

> Guides AI agents on how to maintain the separated custom/ and external/ domains in the Firstsun Skill Arsenal.

- Skill: `firstsun-dev/skill-manager` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add firstsun-dev/skill-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/firstsun-dev/skill-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: firstsun-dev (https://skillmd.com/u/firstsun-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/firstsun-dev/skill-manager

---


# Skill Manager (SM)

## Repository Structure & Flattened Design (扁平化設計)

- `custom/`: Your internal/original skills.
- `external/`: Community skills downloaded for inspection and reference.

### Flattened vs. Conditional Nesting (扁平化與條件式嵌套)
To balance discoverability and organization:
- **Default (Flattened)**: Every skill folder SHOULD be a direct child of its domain folder for default detection by `npx skills add <directory>`.
- **Exception (Conditional Nesting)**: If a domain directory contains **more than 10 skills**, you MAY create one level of sub-directories (categories) to avoid clutter. 
  - *Note*: When nesting is used, users must use `npx skills add <path> --full-depth` to find all skills.
- **Sync Requirement**: Whenever a skill's location changes, you **MUST** immediately update the corresponding link in `SKILLS_LIST.md`.

### Taxonomy Alignment (目錄架構對齊)
To prevent fragmentation (e.g., mixing `search/` and `fetch/` for similar tools), you **MUST** map external skills to our existing local domains/categories:
- **Local Domains**: `basic/`, `develop/`, `obsidian/`, `video-design/`, `writing/`.
- **Ignore Provider Names**: If an external repo uses `research/firecrawl`, but we use `basic/`, move it to `external/basic/firecrawl-search/`.
- **Consistency over Originality**: Always prioritize our folder structure over the external repository's original layout.

## Utility Skills
Leverage these skills to maintain the repository:
- `/find-skills`: Discover existing skills in the ecosystem to avoid duplication.
- `/skills-validator`: Validate skills in `custom/` or `external/` against the agentskills.io spec.
- `/skills-creator`: Follow guided workflows to create new skills with proper structure.

### Refactoring & Efficiency
- **Progressive Disclosure**: Use the `/reference` pattern to keep skills efficient. Read [references/REFACTORING.md](references/REFACTORING.md) for the refactoring SOP.

## Core Commands
- **Single-Skill Update (default for the "Remote Install" SOP step)**: When only one skill changed, run `npx skills add <user>/<repo>/<custom|external>/<domain>/<skill-name>` for that skill alone. Do NOT run `./setup.sh` for a single-skill change — it re-registers every skill in the repo, which is out of scope and can touch unrelated installs.
- Bulk Setup: `./setup.sh` registers **all** local skills (defaults to remote mode to preserve `skills-lock.json`). Reserve this for full onboarding/re-sync (e.g. setting up a new machine), not routine single-skill edits. Use `./setup.sh --local` for active development; the script automatically safeguards `skills-lock.json` from local path changes.
- Bulk Export: `./export.sh <domain>` imports domain skills to a specific project.
- Manual Add: `npx skills add <path_to_directory> -l` to list all detectable skills.

## Gem Export Workflow (Gem 導出流程)
Use this workflow to consolidate multiple skills into a single "Gem" instruction set for Google Gemini.

1. **Identify Categories**: Group related skills (e.g., Lifestyle, Development, Writing).
2. **Extract Essence**: For each skill, extract:
   - Core Role/Persona.
   - Mandates/Principles (Mandates prioritized).
   - Primary Workflows (Step-by-step).
3. **Synthesize**: Combine into a structured prompt:
   - `# Role`: A unified persona (e.g., "The Lifestyle Architect").
   - `# Principles`: Consolidated foundational concepts (e.g., Minerva HCs + Learning Principles).
   - `# Capabilities`: Categorized toolsets (Health, Learning, etc.).
   - `# Interaction Style`: Guidelines for tone and output.
4. **Export**: Write the result to `gem/<category-name>.txt`.

## Plugin Export Workflow (Plugin 導出流程)
Use this workflow to bundle a set of existing skills (e.g. the user's most-used skills) into an installable Claude Code plugin, registered via a local marketplace.

1. **Select Skills**: Decide which skills to bundle. If ranking by usage, scan `~/.claude/projects/*/*.jsonl` for `Skill` tool_use invocations (`input.skill`) and `<command-name>` slash-command tags — merge both, since some skills are only auto-triggered (no matching slash command) and some are only typed.
2. **Verify Source Location**: Confirm each selected skill actually resolves to a real directory under `custom/<domain>/` or `external/<domain>/`. Do not bundle names that turn out to be built-in CLI commands, marketplace-plugin commands, or orphaned skills still sitting in `.agents/skills/` (categorize those into `custom/`/`external/` first, per the SOPs below, before including them).
3. **Scaffold the Plugin**: Create `<plugin-dir>/.claude-plugin/plugin.json` (name, description, version, author) and `<plugin-dir>/skills/`. Inside `skills/`, symlink each bundled skill back to its real location (`ln -s ../../custom/<domain>/<skill> <plugin-dir>/skills/<skill>`) — never copy, so the plugin always tracks the canonical skill content. This makes the plugin local-only (not portable to a fresh clone without the rest of the repo); note that if the plugin is ever meant to be published externally.
4. **Register a Marketplace**: Create or update `.claude-plugin/marketplace.json` at the repo root (`$schema`, `name`, `owner`, `plugins[]` with each plugin's `source` as a relative path, e.g. `"./<plugin-dir>"`).
5. **Validate**: Run `/validate-skills` against every symlinked skill (validation follows symlinks to the real `SKILL.md`, so this re-checks the canonical copy) and sanity-check both `plugin.json` and `marketplace.json` parse as valid JSON.
6. **Document**: Add a `## 🔌 Plugins` entry to `SKILLS_LIST.md` listing the marketplace and each plugin, with the bundled skill names and links to their manifests.
7. **Push**: Commit the new plugin/marketplace files and the `SKILLS_LIST.md` update.
8. **Install**: `/plugin marketplace add <repo-path>` then `/plugin install <plugin-name>@<marketplace-name>`.

## SOP for External Skills
1. **Download**: Run `npx skills add <repo_path>` in root (without -g) to inspect the skill.
2. **Archive**: Move from `.agents/skills/` to `external/<domain>/` (Ensure it is a direct child).
3. **Validate**: Run `/validate-skills` on the archived skill. Fix any FAIL items (name mismatch, body too long, bad link format, missing "when to use") before proceeding.
4. **Document**: Update `SKILLS_LIST.md` with the new skill's name, Chinese description, and link.
5. **Push**: Commit and push changes to GitHub.
6. **Remote Install**: Run `npx skills add <user>/<repo>/external/<domain>/<skill-name>` for that one skill — never `./setup.sh` for a single-skill change.

## SOP for Custom Skills
1. **Create**: Create skill directory in `custom/<domain>/`.
2. **Implement**: Write `SKILL.md` following `skill-creator` guidelines.
3. **Validate**: Run `/validate-skills` on the new skill. Fix any FAIL items before proceeding.
4. **Document**: Add the new skill to `SKILLS_LIST.md`.
5. **Push**: Commit and push changes to GitHub.
6. **Remote Install**: Run `npx skills add <user>/<repo>/custom/<domain>/<skill-name>` for that one skill — never `./setup.sh` for a single-skill change.