feat: implement Claude Skills

[simonpcouch]

This PR ports the skills system from side with a few changes. As in Claude Code, skills are discovered + briefly described at startup (name + description added to system prompt) but only fully loaded when the model calls btw_tool_skills_fetch, keeping the base context lightweight. side had a multi-tool approach to interface with them, but I aligned more closely with Claude Code here where btw uses a single fetch tool that returns the SKILL.md content plus a listing of bundled resources—the model then uses existing file tools to access scripts and references as needed. Skills can be provided by the package (inst/skills/), user config directory, or project-local .btw/skills/ folder.

skills.mov

Opening as draft as there are still some rough edges I'd like to sand off; I'll leave comments on a couple of them now.

[simonpcouch]

I went ahead and ported the "real" skill-creator skill (from Anthropic) by default. I think it's probably worth porting the .py files to .R so that the agent can just source(file-path).

[simonpcouch]

Some existing tools have tools::R_user_dir("btw", which = "cache"). Is this a reasonable directory to look in? I've used ~/.config/{pkg}/ in a few packages, but don't know if this is a Simon-ism. Whatever directory we land on, it should ofc be documented. :)

[gadenbuie]

There's a helper that wraps tools::R_user_dir() -- path_btw_cache(). My take is: this is for cached files used and written by btw. I'm currently only using it for some code related to Shiny bookmarks, but I have plans to have btw_app() remember conversation history and we'd use it there.

Separately, there's path_find_user() that considers these locations:

  possibilities <- c(
    fs::path_home(filename),
    fs::path_home_r(filename),
    fs::path_home(".config", "btw", filename)
  )

So ~/.config/btw/skills would be a natural place to put this that fits in with currently places we look for btw.md. (This is only briefly mentioned in ?btw_client and ?edit_btw_md.)

On the other hand, I could also see ~/.btw/skills making sense.

What do you think about inheriting installed Claude skills too from ~/.claude/skills?

Also: I like using inst/skills just like inst/prompts! I wonder how hard it is to look through installed packages to auto-discover these skills. Or maybe we'd need an option that helps bring in skills from packages.

[simonpcouch]

This is auto-injected into btw_client() (and thus btw_app())'s context, along with a btw_list_skills() summary so that the agent knows what it has access to via a fetch_skill() tool call. This is Claude Code's design.

[simonpcouch]

I would be open to some sort of preferential treatment given to https://github.com/posit-dev/skills as well

[gadenbuie]

I aligned more closely with Claude Code here where btw uses a single fetch tool that returns the SKILL.md content plus a listing of bundled resources—the model then uses existing file tools to access scripts and references as needed.

I really like this, but I wonder if we should have it work a little bit differently in btw where we would have a tool for fetching a skill and a separate tool for fetching resources and another tool for running skill scripts.

(Maybe the fetching skill tool could also get resources with an optional argument.)

There are generally two things that I want to enable. We don't currently have a way to run general system commands, i.e. we don't have an analogous tool to Claude's Bash tool. I'm a little hesitant to create one but much less hesitant about a tool with reduced scope that specifically could run skill scripts.

The other thought is that btw_app() lets you dynamically choose tools within a conversation. It'd be nice to have one skill tool, but tool groups make it easy to include several tools at once, i.e. tools = "skills" should bring in everything you need. We could modify the tool selection logic so that tools = "skills" gives you the read_file tool as well...

Also, dynamically choosing tools means we might not want to inject the available tools into the system prompt. We could instead put them in the tool description. I'm not sure if that makes them more or less effective, but it does mean that we can know we're not adding false directions to the system prompt accidentally.

[simonpcouch]

There are generally two things that I want to enable. We don't currently have a way to run general system commands, i.e. we don't have an analogous tool to Claude's Bash tool. I'm a little hesitant to create one but much less hesitant about a tool with reduced scope that specifically could run skill scripts.

Linking to #148. I guess we would probably still want btw_app() to have access to Skills... maybe btw_app() gets all 4 of those tools, and its more agentic sibling would just get the one.