skilldeck

# SkillDeck Manager Manage AI coding agent skills through natural language. This skill teaches you how to install, update, delete, and assign skills using SkillDeck's filesystem conventions. SkillDeck is a macOS GUI app that manages skills across 14 AI agents. Skills are stored as directories containing `SKILL.md` files. This skill lets you perform the same operations from the terminal. ## Filesystem Layout ``` ~/.agents/ ├── skills/ # Canonical storage (real files live here) │ ├── my-skill/ │ │ ├── SKILL.md # Skill definition (YAML frontmatter + markdown) │ │ └── ... # Other files (scripts, templates, etc.) │ └── another-skill/ │ └── SKILL.md ├── .skill-lock.json # Lock file (v3, shared with npx skills) └── .skilldeck-cache.json # SkillDeck's private cache (do not modify) ~/.claude/skills/ # Claude Code skills (symlinks → canonical) ~/.codex/skills/ # Codex skills (symlinks → canonical, also reads ~/.agents/skills/) ~/.gemini/skills/ # Gemini CLI skills ~/.copilot/skills/ # Copilot CLI skills (also reads ~/.claude/skills/) ~/.config/opencode/skills/ # OpenCode skills (also reads ~/.claude/skills/ and ~/.agents/skills/) ~/.cursor/skills/ # Cursor skills (also reads ~/.claude/skills/) ~/.kiro/skills/ # Kiro skills ~/.codebuddy/skills/ # CodeBuddy skills ~/.openclaw/skills/ # OpenClaw skills ~/.trae/skills/ # Trae skills ~/.qoder/skills/ # Qoder skills ~/.qclaw/skills/ # QClaw skills ~/.workbuddy/skills/ # WorkBuddy skills ~/.gemini/antigravity/skills/ # Antigravity skills ``` **Key rules:** - The real copy of every skill lives in `~/.agents/skills/<name>/` - Each agent gets a **symlink** pointing to the canonical directory - Example: `~/.claude/skills/my-skill` → `~/.agents/skills/my-skill` - Some agents can read other agents' directories (cross-directory inheritance): - **Codex** reads `~/.agents/skills/` natively (no symlink needed) - **Copilot** reads `~/.claude/skills/` - **OpenCode** reads `~/.claude/skills/` and `~/.agents/skills/` - **Cursor** reads `~/.claude/skills/` ## Default Agent Configuration When installing a skill, you need to decide which agents to assign it to. The recommended approach: 1. **Auto-detect installed agents** — check which CLI commands exist on the system 2. **Assign to all detected agents** — unless the user specifies a subset The following script detects installed agents and builds a list of their skills directories: ```bash # Agent detection map: CLI command → skills directory declare -A AGENT_DIRS=( ["claude"]="$HOME/.claude/skills" ["codex"]="$HOME/.codex/skills" ["gemini"]="$HOME/.gemini/skills" ["opencode"]="$HOME/.config/opencode/skills" ["antigravity"]="$HOME/.gemini/antigravity/skills" ["cursor"]="$HOME/.cursor/skills" ["kiro"]="$HOME/.kiro/skills" ["codebuddy"]="$HOME/.codebuddy/skills" ["openclaw"]="$HOME/.openclaw/skills" ["trae"]="$HOME/.trae/skills" ["qoder"]="$HOME/.qoder/skills" ["qclaw"]="$HOME/.qclaw/skills" ["workbuddy"]="$HOME/.workbuddy/skills" ) # Detect which agents are installed INSTALLED_DIRS=() for CMD in "${!AGENT_DIRS[@]}"; do if which "$CMD" &>/dev/null; then INSTALLED_DIRS+=("${AGENT_DIRS[$CMD]}") echo "Detected: $CMD → ${AGENT_DIRS[$CMD]}" fi done # Copilot CLI is a GitHub CLI extension (gh copilot), not a standalone binary. # `which gh` only confirms GitHub CLI is installed, not Copilot specifically. # Check for the copilot extension explicitly. if which gh &>/dev/null && gh extension list 2>/dev/null | grep -q copilot; then INSTALLED_DIRS+=("$HOME/.copilot/skills") echo "Detected: copilot → $HOME/.copilot/skills" fi echo "Found ${#INSTALLED_DIRS[@]} installed agents" ``` Use `INSTALLED_DIRS` as the default target when installing. If the user says "only install for Claude Code", filter to just `$HOME/.claude/skills`. ## Lock File Format Location: `~/.agents/.skill-lock.json` (version 3) ```json { "version": 3, "skills": { "skill-name": { "source": "owner/repo", "sourceType": "github", "sourceUrl": "https://github.com/owner/repo.git", "skillPath": "skills/skill-name/SKILL.md", "skillFolderHash": "abc123...", "installedAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } }, "dismissed": {}, "lastSelectedAgents": [] } ``` **Fields:** - `source`: Repository identifier (e.g., `"crossoverJie/skills"`) or local path - `sourceType`: `"github"`, `"local"`, or `"clawhub"` - `sourceUrl`: Full git URL - `skillPath`: Relative path to SKILL.md within the source - `skillFolderHash`: Git tree hash for update detection (can be empty string for local) - `installedAt` / `updatedAt`: ISO 8601 timestamps ## Helper Functions These reusable snippets are referenced in the operations below. ### List all agent skills directories ```bash # All 14 agent skills directories (for symlink scanning) ALL_AGENT_SKILLS=( "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.gemini/skills" "$HOME/.copilot/skills" "$HOME/.config/opencode/skills" "$HOME/.gemini/antigravity/skills" "$HOME/.cursor/skills" "$HOME/.kiro/skills" "$HOME/.codebuddy/skills" "$HOME/.openclaw/skills" "$HOME/.trae/skills" "$HOME/.qoder/skills" "$HOME/.qclaw/skills" "$HOME/.workbuddy/skills" ) ``` ### Find which agents have a skill installed ```bash # Usage: find_skill_agents "my-skill" "$HOME/.agents/skills/my-skill" find_skill_agents() { local SKILL_NAME="$1" local CANONICAL="$2" for DIR in "${ALL_AGENT_SKILLS[@]}"; do local LINK="$DIR/$SKILL_NAME" if [ -L "$LINK" ]; then local RESOLVED=$(python3 -c "import os; print(os.path.realpath('$LINK'))") if [ "$RESOLVED" = "$CANONICAL" ]; then echo "$DIR" fi fi done } ``` ### Create symlinks for multiple agents ```bash # Usage: create_symlinks "my-skill" "$HOME/.agents/skills/my-skill" "${TARGET_DIRS[@]}" create_symlinks() { local SKILL_NAME="$1" local CANONICAL="$2" shift 2 local TARGET_DIRS=("$@") for DIR in "${TARGET_DIRS[@]}"; do mkdir -p "$DIR" if [ ! -L "$DIR/$SKILL_NAME" ]; then ln -s "$CANONICAL" "$DIR/$SKILL_NAME" echo " Symlink: $DIR/$SKILL_NAME" fi done } ``` ### Remove symlinks from multiple agents ```bash # Usage: remove_symlinks "my-skill" "$HOME/.agents/skills/my-skill" remove_symlinks() { local SKILL_NAME="$1" local CANONICAL="$2" for DIR in "${ALL_AGENT_SKILLS[@]}"; do local LINK="$DIR/$SKILL_NAME" if [ -L "$LINK" ]; then local RESOLVED=$(python3 -c "import os; print(os.path.realpath('$LINK'))") if [ "$RESOLVED" = "$CANONICAL" ]; then rm "$LINK" echo " Removed: $LINK" fi fi done } ``` ## Operations ### 1. Install a Skill from GitHub **Steps:** 1. Clone the repository to a temporary directory 2. Locate the SKILL.md file and the skill directory 3. Detect installed agents (or use user-specified targets) 4. Copy the skill directory to `~/.agents/skills/<name>/` 5. Create symlinks for target agents 6. Update the lock file ```bash # === Configuration === SKILL_NAME="my-skill" REPO_SOURCE="owner/repo" REPO_URL="https://github.com/owner/repo.git" SKILL_FOLDER_PATH="skills/$SKILL_NAME" # path to skill directory within repo # === 1. Clone repo === TMPDIR=$(mktemp -d) git clone --depth 1 "$REPO_URL" "$TMPDIR/repo" # === 2. Locate skill directory === # Two path concepts (matching SkillManager's convention): # SKILL_FOLDER_PATH — directory containing SKILL.md (for git tree hash) # SKILL_FILE_PATH — path to SKILL.md itself (for lock file's skillPath) # Examples: # Sub-directory: folder="skills/foo", file="skills/foo/SKILL.md" # Root-level: folder="", file="SKILL.md" SOURCE_DIR="$TMPDIR/repo/$SKILL_FOLDER_PATH" if [ ! -f "$SOURCE_DIR/SKILL.md" ]; then # Fallback: search for SKILL.md FOUND=$(find "$TMPDIR/repo" -name "SKILL.md" -maxdepth 3 | head -1) if [ -n "$FOUND" ]; then SOURCE_DIR=$(dirname "$FOUND") # Derive folder path as relative path from repo root (empty string for root-level) SKILL_FOLDER_PATH="${SOURCE_DIR#$TMPDIR/repo/}" # Remove trailing slash if present (root case: "$TMPDIR/repo/" → "") SKILL_FOLDER_PATH="${SKILL_FOLDER_PATH%/}" else echo "❌ SKILL.md not found in repository" rm -rf "$TMPDIR" exit 1 fi fi # Derive SKILL_FILE_PATH for lock entry: folder path + "/SKILL.md", or just "SKILL.md" at root if [ -z "$SKILL_FOLDER_PATH" ]; then SKILL_FILE_PATH="SKILL.md" else SKILL_FILE_PATH="$SKILL_FOLDER_PATH/SKILL.md" fi # === 3. Check not already installed === CANONICAL="$HOME/.agents/skills/$SKILL_NAME" if [ -d "$CANONICAL" ]; then echo "❌ Skill '$SKILL_NAME' already exists. Use update instead." rm -rf "$TMPDIR" exit 1 fi # === 4. Detect target agents (auto-detect all installed) === declare -A AGENT_DIRS=( ["claude"]="$HOME/.claude/skills" ["codex"]="$HOME/.codex/skills" ["gemini"]="$HOME/.gemini/skills" ["opencode"]="$HOME/.config/opencode/skills" ["antigravity"]="$HOME/.gemini/antigravity/skills" ["cursor"]="$HOME/.cursor/skills" ["kiro"]="$HOME/.kiro/skills" ["codebuddy"]="$HOME/.codebuddy/skills" ["openclaw"]="$HOME/.openclaw/skills" ["trae"]="$HOME/.trae/skills" ["qoder"]="$HOME/.qoder/skills" ["qclaw"]="$HOME/.qclaw/skills" ["workbuddy"]="$HOME/.workbuddy/skills" ) TARGET_DIRS=() for CMD in "${!AGENT_DIRS[@]}"; do if which "$CMD" &>/dev/null; then TARGET_DIRS+=("${AGENT_DIRS[$CMD]}") fi done # Copilot CLI is a gh extension, not a standalone binary — check explicitly if which gh &>/dev/null && gh extension list 2>/dev/null | grep -q copilot; then TARGET_DIRS+=("$HOME/.copilot/skills") fi