### Execute Install Command Logic

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Handles the core logic for installing skills, including checking for existing setup, cloning repositories, identifying skills, and prompting for selection. Use this for installing skills from a given source.

```typescript
import { Command } from 'commander';
import { join } from 'path';
import { SKILLS_MANAGER_DIR } from '../constants.js';
import { GitService } from '../services/git.js';
import { SkillsService } from '../services/skills.js';
import { InstallOptions } from '../types.js';
import { fileExists, getDirectoriesInDir } from '../utils/fs.js';
import { promptSkillsToInstall } from '../utils/prompts.js';

export async function executeInstall(
  source: string,
  options: InstallOptions
): Promise<void> {
  if (!fileExists(SKILLS_MANAGER_DIR)) {
    console.log('Skills manager not set up. Run: skillsmgr setup');
    process.exit(1);
  }

  const gitService = new GitService();

  // Check if this is a specific skill URL
  if (gitService.isSpecificSkillUrl(source)) {
    const skillPath = gitService.cloneSpecificSkill(source, options.custom || false);
    if (skillPath) {
      console.log(`✓ Installed skill to ${skillPath}`);
    } else {
      console.log('Failed to parse skill URL');
      process.exit(1);
    }
    return;
  }

  // Clone the repository
  const repoPath = gitService.clone(source, options.custom || false);

  // Find all skills in the repo
  const skillDirs = getDirectoriesInDir(repoPath);
  const skills: Array<{ name: string; description: string; path: string }> = [];

  for (const dir of skillDirs) {
    const skillMdPath = join(dir.path, 'SKILL.md');
    if (fileExists(skillMdPath)) {
      // Parse SKILL.md for description
      const service = new SkillsService(SKILLS_MANAGER_DIR);
      const allSkills = service.getAllSkills();
      const skill = allSkills.find((s) => s.path === dir.path);
      skills.push({
        name: dir.name,
        description: skill?.description || '',
        path: dir.path,
      });
    }
  }

  if (skills.length === 0) {
    console.log('No skills found in repository');
    return;
  }

  console.log(`Found ${skills.length} skills.\n`);

  // If --all flag, install all
  if (options.all) {
    console.log(`✓ Installed ${skills.length} skills to ${repoPath}`);
    return;
  }

  // Otherwise, prompt for selection
  const selectedNames = await promptSkillsToInstall(skills);

  if (selectedNames.length === 0) {
    console.log('No skills selected');
    return;
  }

  // For skills not selected, we could remove them, but for simplicity
  // we just report what was installed
  console.log(`\n✓ Installed ${selectedNames.length} skills to ${repoPath}`);
}

export const installCommand = new Command('install')
  .description('Download skills from a repository')
  .argument('<source>', 'Repository URL or "anthropic" for official skills')
  .option('--all', 'Install all skills without prompting')
  .option('--custom', 'Install to custom/ instead of community/')
  .action(async (source: string, options: InstallOptions) => {
    await executeInstall(source, options);
  });

```

--------------------------------

### TypeScript Setup Command for Skills Manager

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Implements the `setup` command for the Skills Manager in TypeScript. It initializes the ~/.skills-manager directory, creates necessary subdirectories, and copies an example skill template if it doesn't exist.

```typescript
import { Command } from 'commander';
import { join } from 'path';
import { fileURLToPath } from 'url';
import { dirname } from 'path';
import { SKILLS_MANAGER_DIR, SKILL_SOURCES } from '../constants.js';
import { ensureDir, copyDir, fileExists } from '../utils/fs.js';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

export async function executeSetup(): Promise<void> {
  console.log(`Creating ${SKILLS_MANAGER_DIR}...`);

  // Create source directories
  for (const source of SKILL_SOURCES) {
    const dir = join(SKILLS_MANAGER_DIR, source);
    ensureDir(dir);
    console.log(`✓ Created ${source}/`);
  }

  // Copy example skill template
  const templateDir = join(__dirname, '..', 'templates', 'example-skill');
  const targetDir = join(SKILLS_MANAGER_DIR, 'custom', 'example-skill');

  if (!fileExists(targetDir)) {
    copyDir(templateDir, targetDir);
    console.log('✓ Created custom/example-skill/SKILL.md');
  } else {
    console.log('· custom/example-skill already exists, skipping');
  }

  console.log('
Setup complete!
');
  console.log('Next steps:');
  console.log('  skillsmgr install anthropic    # Download official Anthropic skills');
  console.log('  skillsmgr list                 # View available skills');
  console.log('  skillsmgr init                 # Deploy skills to your project');
}

export const setupCommand = new Command('setup')
  .description('Initialize ~/.skills-manager/ directory structure')
  .action(async () => {
    await executeSetup();
  });

```

--------------------------------

### Useful Install Options

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Provides options for installing skills, such as installing all discovered skills, specific skills by name, or treating the source as custom.

```bash
npx skillsmgr install anthropics/skills --all
```

```bash
npx skillsmgr install anthropics/skillss/skills -s code-review -s commit-message
```

```bash
npx skillsmgr install https://github.com/user/repo --custom
```

--------------------------------

### Install Skill from Local Directory or Archive

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs skills from a local directory (path must start with './' or '/') or a zip file/.skill package. Can also install into a custom group.

```bash
npx skillsmgr install ./my-skill
```

```bash
npx skillsmgr install ./skills-archive.zip
```

```bash
npx skillsmgr install ./my-skill.skill
```

```bash
npx skillsmgr install ./my-skill --group my-tools
```

--------------------------------

### Install Skill from Registry

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs a skill by its package name from the registry. Dependencies are automatically resolved. Use this to install a specific version by appending '@version'.

```bash
npx skillsmgr install code-review
```

```bash
npx skillsmgr install code-review@1.0.0
```

```bash
npx skillsmgr search code
```

--------------------------------

### Installation of Unregistered Repo Under Official Owner

Source: https://github.com/jtianling/skills-manager/blob/main/openspec/changes/archive/2026-03-27-multi-repo-official-providers/specs/owner-level-official/spec.md

Explains the installation process for a repository that belongs to an official owner but is not explicitly registered in the provider's repository list. The system installs it via GitHub URL but categorizes it as official.

```bash
skillsmgr install vercel-labs/new-repo
```

--------------------------------

### Shorthand Installation: Non-Official Owner/Repo

Source: https://github.com/jtianling/skills-manager/blob/main/openspec/changes/archive/2026-03-27-multi-repo-official-providers/specs/owner-level-official/spec.md

Details the installation flow when a user provides a shorthand `owner/repo` that does not match any official provider (`findOfficialProvider` returns `null`). The system redirects to a community installation process via GitHub URL.

```bash
skillsmgr install random-user/some-repo
```

--------------------------------

### Install a Skill

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs a skill into the central repository located at ~/.skills-manager/. This is the first step to making a skill available for deployment.

```bash
npx skillsmgr install code-review
```

--------------------------------

### Commit Example Skill Template

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Shows the Git command to stage and commit the example skill template files.

```bash
git add src/templates/example-skill/SKILL.md
git commit -m "feat: add example skill template"
```

--------------------------------

### Install Skill from Local Directory or Archive

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs a skill from a local directory or a zip/.skill archive file. This is useful for local development or distributing skills offline.

```bash
npx skillsmgr install ./my-skill
```

```bash
npx skillsmgr install ./skills-archive.zip
```

--------------------------------

### Example Skill Markdown Template

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

A template for creating new skills, including YAML frontmatter for metadata and markdown content for instructions. Use this as a starting point for custom skill development.

```markdown
---
name: example-skill
description: An example skill template. Use when you want to understand how to create custom skills.
---

# Example Skill

This is a template to help you create your own skills.

## SKILL.md Structure

Every skill needs a `SKILL.md` file with two parts:

1. **YAML Frontmatter** (between `---` markers)
   - `name`: Short identifier for the skill
   - `description`: Explains what the skill does and when to use it

2. **Markdown Content**
   - Instructions the AI follows when the skill is invoked

## Tips for Writing Skills

- Be specific in the description - it determines when the skill activates
- Keep instructions clear and actionable
- You can add supporting files (scripts, templates) in the same directory

```

--------------------------------

### Install a Single Skill from a Repository

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs a specific skill from a GitHub repository. The skill is identified by its name after the repository path.

```bash
npx skillsmgr install obra/superpowers:my-skill
```

--------------------------------

### Commit Setup Command File

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Shows the Git command to stage and commit the newly created TypeScript setup command file.

```bash
git add src/commands/setup.ts
git commit -m "feat: add setup command"
```

--------------------------------

### Install Skills from GitHub Repository

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs skills from a specified GitHub repository. Supports shorthand and full URLs for the repository.

```bash
npx skillsmgr install anthropics/skills
```

```bash
npx skillsmgr install https://github.com/user/skills-repo
```

--------------------------------

### Shorthand Installation: Registered Repo

Source: https://github.com/jtianling/skills-manager/blob/main/openspec/changes/archive/2026-03-27-multi-repo-official-providers/specs/owner-level-official/spec.md

Describes the outcome when a user installs a repository using the `owner/repo` shorthand, and `findOfficialProvider` returns `exactRepoMatch: true`. The system uses `installFromOfficial` to install only the specified repository.

```bash
skillsmgr install vercel-labs/agent-skills
```

--------------------------------

### Full Skill Manifest Example

Source: https://github.com/jtianling/skills-manager/blob/main/docs/skill-manifest-reference.md

An example of a complete skill.json manifest, including name, version, description, author, license, target agents, and companion file configurations.

```json
{
  "name": "jt-codex",
  "version": "0.4.0",
  "description": "Run Codex CLI from inside Claude Code via a subagent.",
  "author": "jtianling",
  "license": "MIT",
  "targetAgents": ["claude-code"],
  "companions": [
    {
      "source": "agents/jt-codex-runner.md",
      "agentTargets": {
        "claude-code": ".claude/agents/jt-codex-runner.md"
      }
    }
  ]
}
```

--------------------------------

### Install Skill from GitHub Repository

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs skills from a GitHub repository using the owner/repo shorthand, a full GitHub URL, or a specific skill path within the repository.

```bash
npx skillsmgr install Fission-AI/OpenSpec
```

```bash
npx skillsmgr install https://github.com/user/skills-repo
```

```bash
npx skillsmgr install https://github.com/anthropics/skills/tree/main/skills/code-review
```

--------------------------------

### Copy and Edit Skill Directory

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Demonstrates the process of copying an example skill directory and preparing it for customization.

```bash
cp -r example-skill my-new-skill
Edit my-new-skill/SKILL.md with your content
skillsmgr add my-new-skill
```

--------------------------------

### Git add and commit for initial setup

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Stages all initial project configuration files and commits them with a descriptive message. This establishes the baseline for version control.

```bash
git add package.json tsconfig.json tsup.config.ts vitest.config.ts .gitignore package-lock.json
git commit -m "chore: initial project setup with build configuration"
```

--------------------------------

### Full Workflow Integration Test

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Executes a comprehensive test of the Skills Manager CLI workflow, from setup and installation to adding, removing, and syncing skills within a test project.

```bash
# Setup
node dist/index.js setup

# Install official skills (if available)
node dist/index.js install anthropic --all

# List skills
node dist/index.js list

# Create test project
mkdir /tmp/test-project && cd /tmp/test-project

# Init with skills
node ~/path/to/skills-manager/dist/index.js init

# List deployed
node ~/path/to/skills-manager/dist/index.js list --deployed

# Add a skill
node ~/path/to/skills-manager/dist/index.js add example-skill

# Remove a skill
node ~/path/to/skills-manager/dist/index.js remove example-skill

# Sync
node ~/path/to/skills-manager/dist/index.js sync

```

--------------------------------

### Install Official Anthropic Skills

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Installs all official Anthropic skills or a specific subset. Use the --all flag to install every discovered skill without prompting.

```bash
npx skillsmgr install anthropics/skills
```

```bash
npx skillsmgr install anthropics/skills --all
```

--------------------------------

### Risk Mitigation: BundleManager and Install Subprocess Coupling

Source: https://github.com/jtianling/skills-manager/blob/main/openspec/changes/w03-bundle-aware-update-uninstall/design.md

To reduce coupling between BundleManager and the install subprocess, a shared helper function will be extracted from the common parts of the install logic. BundleManager will then call this helper function instead of directly invoking install.ts.

```typescript
BundleManager 依赖 install 子流程, 代码耦合 | D6 把共享部分抽 helper; BundleManager 只调 helper 不直接调 install.ts
```

--------------------------------

### Skill Dependencies Example

Source: https://github.com/jtianling/skills-manager/blob/main/README.md

Shows how to declare dependencies for a skill, supporting registry packages, specific GitHub skills, and entire GitHub repositories.

```json
"dependencies": [
  "base-prompts",
  "anthropics/skills:code-review",
  "owner/repo"
]
```

--------------------------------

### Prompt for Skill Installation Selection

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Prompts the user to select skills to install using a checkbox interface. Displays skill names and descriptions. Requires 'inquirer'.

```typescript
export async function promptSkillsToInstall(
  skills: Array<{ name: string; description: string }>
): Promise<string[]> {
  const choices = skills.map((skill) => ({
    name: `${skill.name.padEnd(20)} ${skill.description}`,
    value: skill.name,
  }));

  const { selectedSkills } = await inquirer.prompt([
    {
      type: 'checkbox',
      name: 'selectedSkills',
      message: 'Select skills to install:',
      choices,
      pageSize: 20,
    },
  ]);

  return selectedSkills;
}
```

--------------------------------

### CLI Entry Point

Source: https://github.com/jtianling/skills-manager/blob/main/docs/plans/2026-02-03-skills-manager-implementation.md

Sets up the main 'skillsmgr' CLI application using commander.js, defining its name, description, version, and registering all available commands.

```typescript
import { Command } from 'commander';
import { setupCommand } from './commands/setup.js';
import { installCommand } from './commands/install.js';
import { listCommand } from './commands/list.js';
import { initCommand } from './commands/init.js';
import { addCommand } from './commands/add.js';
import { removeCommand } from './commands/remove.js';
import { syncCommand } from './commands/sync.js';

const program = new Command();

program
  .name('skillsmgr')
  .description('Unified skills manager for AI coding tools')
  .version('0.1.0');

program.addCommand(setupCommand);
program.addCommand(installCommand);
program.addCommand(listCommand);
program.addCommand(initCommand);
program.addCommand(addCommand);
program.addCommand(removeCommand);
program.addCommand(syncCommand);

program.parse();

```

--------------------------------

### Migration Log Example

Source: https://github.com/jtianling/skills-manager/blob/main/openspec/changes/archive/2026-04-15-group-as-first-class-unit/design.md

An example of the log output during the Skills Manager data migration process, indicating successful migrations, upgrades, and any naming conflicts encountered.

```log
Migrating skills-manager data...
  ✓ sources.json V2 → V3: 3 local-batch bundles → physical groups
  ✓ groups.json V1 → V2: 5 groups upgraded
  ⚠ Group naming conflict: virtual group 'tdd-spec' renamed to 'tdd-spec-legacy'
    (a physical group with the same name was migrated from local-batch bundle)
  Migration complete.
```

--------------------------------

### CLI: Deploy All - Create Manifest

Source: https://github.com/jtianling/skills-manager/blob/main/openspec/changes/add-deployment-manifest/specs/deployment-manifest/spec.md

Scenario for creating a new deployment manifest when none exists. The 'pinnedSkills' field will include all skills deployed in the current operation.

```bash
skillsmgr deploy --all
```