AgentsSkillVault

gem "agents_skill_vault"

require "agents_skill_vault"

# Create a vault in a directory
vault = AgentsSkillVault::Vault.new(storage_path: "~/.my_vault")

# Let's assume we have this Github Repo

# that has this organisation
# .
# ├── LICENSE
#└── skills
#    ├── commit-message
#    │   └── SKILL.md
#    ├── improving-testing
#    │   └── SKILL.md
#    └── pr-description
#        └── SKILL.md

# Add a full repository
vault.add("https://github.com/lucianghinda/agentic-skills")

# But you can also add a specific skill
# Add a specific folder and even add a custom label
vault.add(
  "https://github.com/nateberkopec/dotfiles/tree/main/files/home/.claude/skills/readme-writer",
  label: "readme-writer"
)

# List all resources
vault.list.each do |resource|
  puts "#{resource.label} -> #{resource.local_path}"
end

# This will output

# lucianghinda/agentic-skills/commit-message -> /Users/lucian/.my_vault/lucianghinda/agentic-skills
# lucianghinda/agentic-skills/improving-testing -> /Users/lucian/.my_vault/lucianghinda/agentic-skills
# lucianghinda/agentic-skills/pr-description -> /Users/lucian/.my_vault/lucianghinda/agentic-skills
# readme-writer -> /Users/Lucian/.my_vault/nateberkopec/dotfiles/files/home/.claude/skills/readme-writer

# Sync a specific resource
result = vault.sync("rails/rails")
puts "Synced!" if result.success?

# Sync all resources
vault.sync_all

vault = AgentsSkillVault::Vault.new(storage_path: "/path/to/vault")

# Add a repository (auto-generates label: "username/repo")
vault.add("https://github.com/user/repo")

# Add with custom label
vault.add("https://github.com/user/repo", label: "my-custom-label")

# Add a specific folder (uses sparse checkout)
vault.add("https://github.com/user/repo/tree/main/lib/skills")

# Add a specific file
vault.add("https://github.com/user/repo/blob/main/config.yml")

# List all resources
resources = vault.list

# Find by label (returns nil if not found)
resource = vault.find_by_label("user/repo")

# Fetch by label (raises Errors::NotFound if not found)
resource = vault.fetch("user/repo")

# Filter by GitHub username
vault.filter_by_username("octocat")  # => [Resource, ...]

# Filter by repository name
vault.filter_by_repo("dotfiles")  # => [Resource, ...]

# Sync a single resource
result = vault.sync("user/repo")
if result.success?
  puts "Changes: #{result.changes?}"
else
  puts "Error: #{result.error}"
end

# Sync all resources
results = vault.sync_all
results.each do |label, result|
  status = result.success? ? "OK" : result.error
  puts "#{label}: #{status}"
end

# Remove from manifest only (keep files on disk)
vault.remove("user/repo")

# Remove from manifest AND delete files
vault.remove("user/repo", delete_files: true)

# Export manifest for backup
vault.export_manifest("/backups/manifest.json")

# Import manifest (merges with existing resources)
vault.import_manifest("/shared/manifest.json")

# Re-download all resources from scratch
vault.redownload_all

resource = vault.fetch("user/repo")

resource.label          # => "user/repo"
resource.url            # => "https://github.com/user/repo"
resource.username       # => "user"
resource.repo           # => "repo"
resource.type           # => :repo, :folder, or :file
resource.branch         # => "main"
resource.local_path     # => "/vault/user/repo"
resource.relative_path  # => nil (or path within repo for folders/files)
resource.added_at       # => Time
resource.synced_at      # => Time

result = vault.sync("user/repo")

result.success?  # => true/false
result.changes?  # => true/false (did the sync pull new changes?)
result.error     # => nil or error message string

begin
  vault.add("invalid-url")
rescue AgentsSkillVault::Errors::InvalidUrl => e
  puts "Bad URL: #{e.message}"
end

begin
  vault.fetch("nonexistent")
rescue AgentsSkillVault::Errors::NotFound => e
  puts "Not found: #{e.message}"
end

begin
  vault.add("https://github.com/user/repo")
  vault.add("https://github.com/other/thing", label: "user/repo")
rescue AgentsSkillVault::Errors::DuplicateLabel => e
  puts "Duplicate: #{e.message}"
end

vault = AgentsSkillVault::Vault.new(storage_path: "~/.claude/skill_vault")

# Add skills from various sources
vault.add("https://github.com/anthropics/claude-code/tree/main/skills/web-search")
vault.add("https://github.com/user/my-skills/tree/main/coding-assistant", label: "coding")

# Keep everything up to date
vault.sync_all

# On machine A: Export your vault configuration
vault.export_manifest("~/Dropbox/vault-manifest.json")

# On machine B: Import and download
new_vault = AgentsSkillVault::Vault.new(storage_path: "~/.vault")
new_vault.import_manifest("~/Dropbox/vault-manifest.json")
new_vault.redownload_all

# Instead of cloning a huge monorepo, just get the folder you need
vault.add(
  "https://github.com/big-org/monorepo/tree/main/packages/useful-lib",
  label: "useful-lib"
)