SKM (Skill Manager) is a command-line interface (CLI) tool designed for managing AI agent skills at a global, user-level scope rather than a project-specific one. It automates the process of discovering, installing, and synchronizing skills for various AI agents (e.g., Claude, Codex, OpenClaw) by symlinking them into designated agent directories.

The core methodology of SKM revolves around a declarative configuration file, ~/.config/skm/skills.yaml, which defines the desired state of installed skills. This YAML file specifies packages, each sourced either from a Git repository (repo) or a local directory (local_path). For each package, users can optionally list specific skills to install (skills field) or let SKM detect all available skills. Furthermore, the configuration allows for fine-grained control over which agent directories receive the links, either globally for all packages (agents at the top level) or on a per-package basis (agents within a package entry), including exclusion rules (excludes).

Skill Detection Mechanism:
A "skill" is technically defined as a directory containing a SKILL.md file with YAML frontmatter that includes a mandatory name field. SKM employs a specific detection order when scanning a package source:

1. It first checks if the root of the cloned repository or local path itself contains a SKILL.md file, treating the entire source as a single skill.
2. If not, it checks for the existence of a skills/ subdirectory and scans its immediate children for SKILL.md files.
3. Otherwise, it recursively walks all subdirectories from the repository root, stopping descent into any directory once a SKILL.md file is found within it (thus preventing nested skill detection).

Installation and Synchronization Process (skm install):
When skm install is executed, it treats skills.yaml as the authoritative declarative state:

4. Cloning/Linking Sources: For repo packages, it clones the Git repository into a local store (~/.local/share/skm/skills/). For local_path packages, it directly references the specified directory.
5. Skill Detection: Within each source, it applies the skill detection logic to identify all available skills based on SKILL.md files.
6. Filtering: It filters the detected skills based on the skills list specified in the skills.yaml for each package, if present.
7. Agent Mapping: It determines the target agent directories for each skill based on the global agents configuration and any package-specific agents overrides or excludes. Default agent paths include ~/.claude/skills/, ~/.codex/skills/, ~/.openclaw/skills/, and ~/.agents/skills/ (for standard). These paths can be overridden via CLI arguments like --agents-dir.
8. Symlinking: For each skill intended for installation, SKM creates a symbolic link from its location within the SKM store (or local path) to the respective agent's skill directory.
9. Lock File Management: It maintains a ~/.config/skm/skills-lock.yaml file, which tracks all installed skills and their corresponding links. This lock file is crucial for the idempotent behavior.
10. Idempotency and State Sync: skm install is idempotent. It not only establishes new links but also ensures the agent directories precisely match the skills.yaml configuration by:
    • Deleting symlinks for skills that have been removed from a package's skills list in the configuration.
    • Deleting symlinks for entire packages that have been removed from skills.yaml.
    • Updating or deleting links from agent directories when agents filtering rules (e.g., excludes) change.

Crucially, SKM only manages and affects symlinks it itself created and tracked in skills-lock.yaml, leaving any manually created files or skills installed by other tools untouched.

Direct Installation:
SKM also supports direct installation from a source URL or local path ($skm install <source> [skill]$) without prior skills.yaml modification. This mode interactively prompts the user to select skills and target agents, and then automatically updates skills.yaml to reflect the changes, effectively integrating the direct installation into the declarative management system.

Other Commands:

• skm list: Displays installed skills and their linked paths, with an --all option to show all skills across agent directories, marking those managed by SKM.
• $skm view <source>$: Allows browsing and previewing skills from a given source without installing them.
• skm check-updates: Fetches remote repositories to identify available updates for installed skills (skips local_path sources).
• $skm update <skill>$: Pulls the latest changes for a specific skill's repository, re-detects skills, re-links them, and updates the lock file (also skips local_path sources).

SKM provides a robust and centralized solution for managing AI agent skills by leveraging a declarative configuration, precise skill detection, and systematic symlinking to maintain a synchronized state across various agent environments.