Agent skill — Shadwire

Without context, an agent writing ERB makes things up: it passes icon: to a button, calls ui_carousel in an app that does not have the carousel installed, or writes bg-blue-500 where a token exists. The skill teaches the agent the workflow and the conventions. For the details (component names, variants, arguments, helpers) it has the agent ask the CLI, so the answers match your app.

npx skills add edumoraes/shadwire

The skills installer works with Claude Code, Codex, Cursor, OpenCode, Gemini CLI and about twenty other agents. The skill's source is in skills/shadwire/ in the repository.

The skill does not list components

If the skill listed the components and their variants, the list would be out of date after your first add, and nothing would tell you. Instead, it loads the output of bin/shadwire status --json into the agent's context and tells the agent to read it first.

## Current Project Context

```!
bin/shadwire status --json 2>/dev/null || bundle exec shadwire status --json 2>/dev/null || …
```

That command always returns valid JSON. Three of its fields matter most for what the agent writes:

Field	Why it matters
`installed[].helpers`	The ui_* methods that exist in this app. Calling the helper of a component that is not installed raises NoMethodError.
`stack.importmap`	Whether the interactive components can work. 29 of the 57 components ship a Stimulus controller.
`cli.binstub`	Whether `bin/shadwire` exists. If it is false, the agent runs `init` before anything else.

In the Shadwire repository, CI checks that every helper and command the skill mentions still exists, and runs the workflow it describes from start to finish. If the skill falls out of date, the build fails.

What's in it

File	Contents
`SKILL.md`	Principles, the rules that matter most, the table for choosing a component, and the workflow. Loads bin/shadwire status --json as project context.
`cli.md`	A reference for every command and flag, the shape of the JSON payload, and how to read errors and exit codes.
`theming.md`	Where the tokens live, class-based dark mode, how to retheme, how to add a token, and how to keep edits across updates.
`rules/composition.md`	Subcomponents as nested helpers, items inside their group, mandatory titles on overlays, Stimulus.
`rules/styling.md`	Semantic tokens, class precedence, free-form HTML attributes, Tailwind utility conventions.
`rules/forms.md`	The field family, validation state, wiring into form_with, and choosing the control.
`rules/icons.md`	lucide-rails, kebab-case names, sizes, and when an icon needs an accessible label.

SKILL.md is the entry point, and the other files are references it links to. The same rules are covered on this site under Composition, Styling, Forms and Icons.

The workflow it teaches

bin/shadwire status --json      # 1. what already exists in this app
bin/shadwire search modal       # 2. find the component
bin/shadwire info dialog --json # 3. read the API before writing ERB
bin/shadwire add dialog --yes   # 4. install it
bin/shadwire status --json      # 5. confirm the new helpers

info --json returns the helper names, variants and sizes. Agents skip this step more than any other, and without it they rebuild the component out of divs and utility classes.

Trust the exit code

A non-zero exit code means something was not applied (usually a bundle add), and the message says how to fix it. The skill tells the agent to stop at that point instead of carrying on as if it had worked.

Permissions

The skill's frontmatter declares the tools it needs:

---
name: shadwire
description: Manages shadcn/ui components in Ruby on Rails apps via the shadwire CLI…
user-invocable: false
allowed-tools: Bash(bin/shadwire *), Bash(./bin/shadwire *), Bash(bundle exec shadwire *), Bash(shadwire *)
---

allowed-tools only applies to the turn in which the skill is loaded. To stop the permission prompts for good, add a rule to the app's .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(bin/shadwire *)"]
  }
}

user-invocable: false is on purpose: you don't call this skill yourself. The agent loads it when it works on UI in a Rails app that has a shadwire.json.

Agents without the skill

Not every agent supports skills. The same catalog is also published as plain text, in the llms.txt format: an index that says when to use each component, and a file with the full API. You can paste either one into a model's context.