Idea: Agent Skills for dbc

[ianmcook]

1. Add automation that creates a SKILL.md file per the Agent Skills format spec.

   Some ideas from a conversation with Claude about this:

   Prompt:

   This repo contains the source code and docs for the dbc CLI, a tool for installing ADBC drivers. I would like to make it easier for LLMs to use this tool by providing a SKILL.md file per the Agent Skills specification at https://agentskills.io/specification. Tell me how best to do this.

   Response:

   Creating a SKILL.md for dbc

   Directory Structure

   Create a skill directory at the root of your repo or in a dedicated location:

   dbc/                                                                                                                     
   └── SKILL.md                                                                                                             
   

   The directory name must match the name field in frontmatter, so use dbc for both.

   Key Requirements from the Spec

   1. Frontmatter (required):

      • name: lowercase, hyphens only, max 64 chars, must match directory name
      • description: max 1024 chars, describe what it does and when to use it

   2. Body content: Step-by-step instructions, examples, edge cases

   3. Keep it concise: Under 500 lines recommended for the main file; use references/ for detailed docs

   Recommended SKILL.md Content

   ---                                                                                                                      
   name: dbc                                                                                                                
   description: Install and manage ADBC (Arrow Database Connectivity) drivers. Use when the user needs to install database drivers for Snowflake, PostgreSQL, BigQuery, DuckDB, or other ADBC-supported databases, or when managing driver dependencies in a project.                                                                                                 
   license: Apache-2.0                                                                                                      
   compatibility: Requires dbc CLI to be installed. Works on macOS, Linux, and Windows.                                     
   metadata:                                                                                                                
     author: columnar                                                                                                       
     version: "1.0"                                                                                                         
   ---                                                                                                                      
                                                                                                                            
   # dbc - ADBC Driver Manager                                                                                              
                                                                                                                            
   Install and manage ADBC database drivers.                                                                                
                                                                                                                            
   ## Quick Commands                                                                                                        
                                                                                                                            
   - `dbc install <driver>` - Install a driver (e.g., `dbc install snowflake`)                                              
   - `dbc search [pattern]` - Search available drivers                                                                      
   - `dbc info <driver>` - Get driver details                                                                               
                                                                                                                            
   ## Project Workflow                                                                                                      
                                                                                                                            
   For reproducible driver management in a project:                                                                         
                                                                                                                            
   1. `dbc init` - Create a `dbc.toml` file                                                                                 
   2. `dbc add <driver>` - Add drivers to the list (supports version constraints like `dbc add "postgresql>=13.0"`)         
   3. `dbc sync` - Install all drivers and create `dbc.lock`                                                                
                                                                                                                            
   ## Using Installed Drivers                                                                                               
                                                                                                                            
   After installation, use drivers via Python's adbc-driver-manager:                                                        
                                                                                                                            
   ```python                                                                                                                
   import adbc_driver_manager.dbapi as adbc                                                                                 
                                                                                                                            
   with adbc.connect(driver="snowflake", db_kwargs={...}) as con:                                                           
       cursor = con.cursor()                                                                                                
       cursor.execute("SELECT * FROM table")                                                                                
       table = cursor.fetch_arrow_table()                                                                                   

   Common Drivers

   • snowflake - Snowflake Data Cloud
   • postgresql - PostgreSQL
   • bigquery - Google BigQuery
   • duckdb - DuckDB
   • flightsql - Arrow Flight SQL
   • sqlite - SQLite

   Additional Commands

   • dbc uninstall <driver> - Remove a driver
   • dbc remove <driver> - Remove from dbc.toml
   • dbc docs <driver> - Open driver documentation
   • dbc auth login - Authenticate with private registries

   Where to Place It

   You have two options:

   1. In your repo root: Create a dbc/SKILL.md directory/file at the repo root
   2. Separate distribution: Publish to a skill registry or include in your installation artifacts

   Optional Enhancements

   If you want to provide more detailed reference material without bloating the main file:

   dbc/                                                                                                                     
   ├── SKILL.md                                                                                                             
   └── references/                                                                                                          
       └── REFERENCE.md    # Detailed command reference, all flags, etc.                                                    
   

2. Add a dbc skill subcommand that can install or show this SKILL.md file.

   Ideas from a conversation with Claude about this:

   Prompt:

   How do LLMs that are using dbc get this SKILL.md file? Should we have a dbc subcommand that installs it? What's the
   convention for this?

   Response:

   How Skill Discovery Works

   According to the spec, there are two approaches:

   1. Filesystem-based agents (like Claude Code): Skills are discovered by scanning "configured directories" for folders
      containing SKILL.md. The agent loads metadata at startup and injects it into context.

   2. Tool-based agents: Implement custom tools for skill activation.

   The Gap: No Standard Location

   The spec does not define a standard directory where skills should be installed. It's left to each agent
   implementation to decide where to look. This means:

   • There's no universal registry
   • There's no standard ~/.skills/ or /usr/share/skills/ path defined
   • Each agent (Claude Code, Cursor, etc.) may have its own convention

   Options for dbc

   Option 1: Document manual placement

   Tell users to copy the skill to wherever their agent looks. For Claude Code, this might be a project's .claude/skills/
   or ~/.claude/skills/ directory (though I'd need to verify Claude Code's specific convention).

   Option 2: Add a dbc skill subcommand

   dbc skill install --agent claude-code  # Installs to ~/.claude/skills/dbc/                                               
   dbc skill install --path ./my-skills/  # Installs to custom path                                                         
   dbc skill show                         # Prints the SKILL.md content                                                     

   Option 3: Bundle in installation artifacts

   Include the dbc/SKILL.md directory in your distributed packages and document where it ends up.

   Option 4: Publish to a registry (future)

   The spec mentions a skills-ref reference implementation. A centralized registry may emerge.

   My Recommendation

   For now, I'd suggest:

   1. Include the SKILL.md in your repo at skills/dbc/SKILL.md
   2. Add a simple command like dbc skill that prints the path or content, so users can easily copy it
   3. Document how users should configure their specific agent to find it

[amoeba]

I spent some time tinkering with this.

As for where to put skills and how to install them, I think the thing I'd go with is a dedicated repo. Then a user can run npx skills add columnar-tech/dbc-skills to install to the agent(s) of their choice. Agents are getting plugin systems and a dedicated repo seems to be the easiest for them. Anthropic has a system and I also note that pi does too.

I set up an example repo with a dbc and an adbc skill, you can install it into your agent with npx skills install https://github.com/amoeba/dbc-skills. The dbc skill encourages the agent to use the ADBC skill.

In my minimal testing, this seems to work pretty well and my main take-away was that Sonnet 4.5 is easily confused about how to use Python.

I don't know if we need to get into the weeds of evals but that'd be where I'd go next (setting up an evals repo and crowd-sourcing everyone's ideas for evals).

[amoeba]

I have what I'll call a first version of a dbc skill at https://github.com/amoeba/dbc-skills. I did some really basic evals and it's pretty promising. I tried to make an ADBC skill but I wasn't getting good eval performance so what's on the main is just the dbc skill.

If we like this, I think the next steps could be:

• Copy my repo into the columnar-tech org, update any references in readme. Add license, etc.
• Add a LLMs/Agents guide to the dbc docs
• Maybe? Copy the SKILL.md into our website deploy so people can just get it from https://docs.columnar.tech/dbc/SKILL.md

[esadek]

@amoeba Does it make sense to name the repo something more general like skills or agent-skills so additional ADBC-related skills can be added in the future? Looking at https://skills.sh those seem to be the most common names.

[ianmcook]

I like skills