Install Skill

Install agent skills from local paths, GitHub repositories, or the dot-agents library.

When to Use This Skill

Use install-skill when you need to:

• Add a skill from the dot-agents repository to your project
• Install a custom skill from a local directory
• Fetch and install a skill from a GitHub repository
• Set up skills for the first time in a project
• Share skills between projects

Installation Process

Step 1: Identify the Skill Source

Determine where the skill is located:

Shorthand (from dot-agents repository):

• skills/meta/skill-creator
• skills/meta/skill-tester
• skills/meta/skill-evaluator
• skills/examples/get-weather
• skills/examples/simple-task

Local Path:

• Absolute: /path/to/skill-directory
• Relative: ../skills/my-skill
• Home: ~/custom-skills/my-skill

GitHub URL:

• Full tree URL: https://github.com/user/repo/tree/main/path/to/skill

Step 2: Determine Target Directory

The installation script automatically discovers the skills directory by searching for existing SKILL.md files.

Discovery Priority:

1. .agents/skills/ (project-level, agent-agnostic) - preferred
2. .claude/skills/ (project-level, Claude-specific)
3. ~/.agents/skills/ (global, agent-agnostic)
4. ~/.claude/skills/ (global, Claude-specific)

If no existing skills are found, the script will prompt you to choose a location.

Manual Override: You can specify the target directory as a second argument:

bash scripts/install.sh <skill-source> <target-directory>

Step 3: Run the Installation Script

Check available options:

bash scripts/install.sh --help

Install a skill:

bash scripts/install.sh <skill-source>

Step 4: Verify Installation

Check that the skill was installed correctly:

ls -la <target-directory>
cat <target-directory>/<skill-name>/SKILL.md

Validate the installed skill:

python /path/to/skill-tester/scripts/test_skill.py <target-directory>/<skill-name>

Script Usage

Basic Commands

Show Help:

bash scripts/install.sh --help

Show Version:

bash scripts/install.sh --version

Install from Shorthand:

bash scripts/install.sh skills/meta/skill-creator
bash scripts/install.sh skills/examples/get-weather

Install from Local Path:

bash scripts/install.sh /path/to/custom-skill
bash scripts/install.sh ../skills/my-skill
bash scripts/install.sh ~/custom-skills/my-skill

Install from GitHub:

bash scripts/install.sh https://github.com/user/repo/tree/main/skills/my-skill

Specify Target Directory:

bash scripts/install.sh skills/meta/skill-creator ~/.agents/skills
bash scripts/install.sh skills/examples/get-weather ./.agents/skills

Examples

Example 1: First-Time Setup

Scenario: Setting up skills in a new project

Steps:

1. Create skills directory:

   mkdir -p .agents/skills
   

2. Install skill-creator:

   bash scripts/install.sh skills/meta/skill-creator
   

3. Verify installation:

   ls -la .agents/skills/skill-creator
   

Expected Output:

ℹ Discovering skills installation directory...
⚠ Found empty skills directory: ./.agents/skills
ℹ Target directory: ./.agents/skills
ℹ Found skill locally: /Users/user/dot-agents/worktrees/main/skills/meta/skill-creator
ℹ Installing skill-creator from /Users/user/dot-agents/worktrees/main/skills/meta/skill-creator
✓ Installed skill: skill-creator → ./.agents/skills/skill-creator

Example 2: Installing Multiple Skills

Scenario: Installing several skills from the dot-agents repository

Steps:

bash scripts/install.sh skills/meta/skill-creator
bash scripts/install.sh skills/meta/skill-tester
bash scripts/install.sh skills/meta/skill-evaluator
bash scripts/install.sh skills/examples/get-weather

Result: All skills installed to the same auto-detected directory

Example 3: Installing Custom Skill

Scenario: Installing a skill you developed locally

Steps:

1. Develop skill at ~/my-skills/custom-analyzer/

2. Ensure it has SKILL.md with proper frontmatter

3. Install:

   bash scripts/install.sh ~/my-skills/custom-analyzer
   

Expected Output:

ℹ Discovering skills installation directory...
ℹ Found skills in: ./.agents/skills
ℹ Target directory: ./.agents/skills
ℹ Installing custom-analyzer from /Users/user/my-skills/custom-analyzer
✓ Installed skill: custom-analyzer → ./.agents/skills/custom-analyzer

Example 4: Installing from GitHub

Scenario: Installing a community skill from GitHub

Steps:

bash scripts/install.sh https://github.com/user/repo/tree/main/skills/awesome-skill

Process:

1. Script clones the repository (sparse checkout)
2. Extracts the skill directory
3. Validates SKILL.md exists
4. Installs to auto-detected location

Example 5: Overwriting Existing Skill

Scenario: Updating a skill that's already installed

Steps:

bash scripts/install.sh skills/meta/skill-creator

Interactive Prompt:

⚠ Skill already exists: ./.agents/skills/skill-creator
Overwrite? [y/N]:

Choose y to update, N to cancel.

How Directory Discovery Works

The script searches for existing SKILL.md files in common locations to infer where skills should be installed.

Search Process:

1. Search ./.agents/skills/*/SKILL.md
2. Search ./.claude/skills/*/SKILL.md
3. Search ~/.agents/skills/*/SKILL.md
4. Search ~/.claude/skills/*/SKILL.md

Decision Logic:

• If skills found in .agents/skills/ → use that
• If only found in .claude/skills/ → use that
• If found in multiple locations → use highest priority (agent-agnostic over Claude-specific, local over global)
• If none found but empty directory exists → use that
• If nothing found → prompt user

Skill Name Extraction

The script extracts the skill name from the SKILL.md YAML frontmatter:

---
name: skill-name
description: ...
---

The skill is installed using this name, not the source directory name. This ensures consistency.

Best Practices

• Use shorthand for dot-agents library: Simplest and most reliable
• Verify after installation: Check SKILL.md exists and is readable
• Use .agents/skills/ for projects: Agent-agnostic, future-proof
• Use ~/.agents/skills/ for global skills: Available across all projects
• Validate installed skills: Run skill-tester after installation
• Version control project skills: Commit .agents/skills/ to git for team sharing

Common Pitfalls

• Missing SKILL.md: Source directory must contain valid SKILL.md file
• Name mismatch: Skill installed using YAML name field, not directory name
• Permission errors: Ensure write access to target directory
• Network issues: GitHub installations require internet connection
• Invalid GitHub URL: Must be full tree URL, not just repo URL

Error Handling

Source Not Found:

✗ Source directory does not exist: /path/to/skill

Check path spelling and existence.

SKILL.md Missing:

✗ SKILL.md not found in: /path/to/skill

Source must be a valid skill directory.

Clone Failed:

✗ Failed to clone repository: https://github.com/user/repo

Check URL and network connection.

Name Extraction Failed:

✗ Could not extract skill name from SKILL.md

SKILL.md must have valid YAML frontmatter with name: field.

Dependencies

• bash (version 4.0+)
• git (for GitHub and dot-agents repository installations)
• awk (for YAML parsing)
• find (for directory discovery)

Standard utilities available on macOS and Linux.

Integration with Other Meta-Skills

After Installation:

1. Validate with skill-tester:

   python skill-tester/scripts/test_skill.py .agents/skills/new-skill
   

2. Evaluate with skill-evaluator: Load skill-evaluator and assess the installed skill's quality.

3. Use skill-creator for new skills: Install skill-creator first, then use it to scaffold new skills.

Troubleshooting

Q: Script can't find dot-agents repository

A: Install from GitHub URL or clone the repository locally first.

Q: Installation directory not detected

A: Manually specify target directory as second argument or create .agents/skills/ first.

Q: Skill name doesn't match directory

A: This is expected. The script uses the name field from SKILL.md YAML frontmatter.

Q: Permission denied

A: Check write permissions on target directory or use a different location.

Resources

• Installation script: scripts/install.sh
• Agent Skills Repository: https://github.com/tnez/dot-agents
• Agent Skills Specification: https://github.com/anthropics/skills/blob/main/agent_skills_spec.md