Essential Ruby Gems for Working with Agent Skills Files

I have created a couple of gems as a foundation for creating more tools to support agents in Ruby. They are very small building blocks to be used by more complex tools.

I know there are already packages in JavaScript or other languages, but I wanted to have a couple of tools written in Ruby to be included in other (more complex) DX tools.

Why Ruby for Agent Tooling?

Ruby is both a scripting language and a web development language. This dual nature makes it a good fit suited for building developer experience tools. While most AI agent tooling exists in the JavaScript ecosystem, there is value in having native Ruby implementations that integrate naturally with Ruby workflows and Rails applications.

The future of building terminal user interfaces (TUI) with Ruby is getting easier. With libraries like Charm and Ratatui offering Ruby wrappers, the possibilities for creating sophisticated command-line tools are expanding.

Three Foundation Gems

I built three gems that work together to provide basic infrastructure for AI agent tooling:

1. agent_skills_configurations

A unified interface for discovering and accessing skill configuration paths for various AI coding agents.

It will give you the configuration location/folder per each installed (or not) AI coding agent. This solves the problem of knowing where different agents store their skills and configurations across different systems.

Key features:

• Detect installed AI coding agents

• Get configuration paths for each agent

• Unified interface regardless of agent type

GitHub: https://github.com/lucianghinda/agent_skills_configurations

require "agent_skills_configurations"

# Find a specific agent
agent = AgentSkillsConfigurations.find("cursor")
agent.name              # => "cursor"
agent.display_name      # => "Cursor"
agent.skills_dir        # => ".cursor/skills"
agent.global_skills_dir # => "/Users/username/.cursor/skills"

# List all detected agents
AgentSkillsConfigurations.detected.map(&:name)
# => ["cursor", "claude-code", "windsurf", ...]

# List all configured agents (49+ supported)
AgentSkillsConfigurations.all.map(&:name)
# => ["amp", "claude-code", "cursor", "codex", "windsurf", ...]

2. agent_skill_parser

A Ruby gem for parsing skill files that use YAML frontmatter and markdown body content.

It will parse an AgentSkill file according with specifications from agentskills dot io and return an object with those properties. This makes it easy to programmatically work with agent skills, validate them, and extract metadata.

Key features:

• Parse YAML frontmatter from skill files

• Extract markdown body content

• Return structured objects for easy manipulation

• Follow agentskills.io specifications

GitHub: https://github.com/lucianghinda/agent_skill_parser

Taking an example of a markdown for an Agent Skill like this one:

---
name: pdf-processing
description: Extract text from PDF documents using various parsing strategies
license: Apache-2.0
compatibility: OpenAI Anthropic
metadata:
  author: Acme Inc
  version: 1.0.0
  category: document-processing
allowed-tools: Bash(git:*) Read
---

## Instructions

This skill helps extract text from PDFs.

### Step 1: Download the PDF
Use the Bash tool to download PDF files from URLs.

skill = AgentSkillParser.parse("path/to/skill.md")

skill.name          # => "pdf-processing"
skill.description   # => "Extract text from PDF documents..."
skill.body          # => "## Instructions\n\nThis skill helps..."

fm = skill.frontmatter

fm.name             # => "pdf-processing"
fm.description      # => "Extract text from PDF documents..."
fm.license          # => "Apache-2.0"
fm.compatibility    # => "OpenAI Anthropic"
fm.metadata         # => {"author" => "Acme Inc", "version" => "1.0.0", "category" => "document-processing"}
fm.allowed_tools    # => [#<AllowedTool name="Bash" pattern="git:*">, ...]

tool = skill.frontmatter.allowed_tools.first

tool.name    # => "Bash"
tool.pattern # => "git:*"

3. agents_skill_vault

A gem that can manage a vault (a local folder) with various skills from Github URLs.

Basically you can give it a list of Agent Skills (or repositories) and it will download and sync them on a local folder. This becomes the foundation for managing collections of skills, keeping them updated, and distributing them across teams.

Key features:

• Download skills from GitHub repositories

• Manage local skill collections

• Sync skills to keep them updated

• Support for multiple skill sources

GitHub: https://github.com/lucianghinda/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

Building with AI Assistance

The code created for them was generated using a combination of Claude Code + GLM via Claude Code, OpenCode and Moltbot.

I reviewed all the code and manually refined it until I got a version that is good enough for release. This approach allowed me to quickly scaffold the basic structure and functionality, while maintaining control over the final implementation quality.

AI-assisted development worked well for:

• Initial project structure and boilerplate

• Basic implementation patterns

• Test scaffolding

• Documentation templates

Human review was essential for:

• API design decisions

• Edge case handling

• Code organization and clarity

• Ensuring consistency across all three gems

What You Can Build

I have in mind a couple of tools:

Team skill management: Create CLI tools that distribute and sync approved agent skills across your team. No more manual copying of configuration files or sharing snippets in Slack.

Skill validation: Build tools that parse and validate agent skills before they are used. Check for required fields, verify tool permissions, and ensure skills follow your team's standards.

Skill discovery: Create dashboards or search tools that help developers find and understand available agent skills. Parse skills from multiple sources, display their capabilities, and show which agents support them.

Automation workflows: Build scripts that keep agent skills synchronized across different agents (Cursor, Windsurf, etc.). Update a skill once, distribute it everywhere.

Internal registries: Combine all three gems to build skill marketplaces or internal registries where developers can browse, test, and install skills with confidence.

Looking Forward

I want to see more gems or libraries built with Ruby to provide a great foundation of DX. The Ruby ecosystem has an excellent developer experience. Here are some examples that maybe now they are taken for granted: IRB + Rails console, rake …

These three gems are a starting point. A lot of improvements can be made, but I think they can provide a solid foundation to build more gems on top of them.

All three are open source and available on GitHub under Apache 2.0 License. In case you wonder why Apache 2.0 Licence that is mainly as it explicitely defines the license for contributions.