Anatomy of SKILL.md

Every skill is a single Markdown file with a YAML frontmatter block at the top and a body of instructions below. The structure is simple but each part has a specific job.

The Full Structure

---
name: rails-service-objects
description: Generate service objects in a Rails app following the
  project's established patterns. Use this skill whenever the user
  asks to add business logic, extract code from a controller, create
  a service, or implement an operation class. Also trigger for any
  mention of "service layer", "PORO", or "business logic class".
---

# Rails Service Objects

Short intro paragraph explaining what this skill covers.

## Convention

The specific conventions to follow — naming, file location, structure.

## Template

The actual code template or pattern to use.

## Examples

Before/after or usage examples.

## Notes

Edge cases, gotchas, things to avoid.
SKILL.md

The Three Layers

Required vs Optional Fields

File System Layout

# Simple skill — just a SKILL.md
rails-service-objects/
└── SKILL.md

# Complex skill with resources
rails-full-resource/
├── SKILL.md           # Main instructions + pointers to references
├── scripts/
│   └── scaffold.sh    # Shell scripts Claude can run
├── references/
│   ├── hotwire.md     # Framework-specific docs
│   └── rspec.md
└── assets/
    └── spec_template.rb  # Code templates
Structure

The Description Field

The description is the most critical part of your skill. It's the only thing Claude reads when deciding whether to consult your skill — get it wrong and your skill never fires, no matter how good the body is.

What It Needs to Do

• Tell Claude what the skill does
• Tell Claude when to trigger it — the specific contexts, phrases, and request types
• Be "pushy" — Claude naturally under-triggers skills, so the description should lean toward triggering
• Include synonyms and alternate phrasings users might say

Good vs Bad Descriptions

description: Helps with Rails development.

description: Generate Rails service objects,
  POROs, and operation classes. Use whenever
  the user wants to extract business logic,
  add a service layer, or mentions "service
  object", "operation class", "interactor",
  or "command pattern" in a Rails context.

description: A skill for creating RSpec
  tests in Rails projects.

description: Write RSpec tests for Rails
  models, controllers, and services. Trigger
  for any request to "write a test", "add
  specs", "test this", "write unit tests",
  or "cover this with tests" in a Rails app.

The Anatomy of a Great Description

description: # Part 1: What does it do?
  Generate database migrations for Rails apps following
  safe, reversible migration patterns.
  # Part 2: When to trigger (explicit contexts)
  Use this skill whenever the user asks to add a column,
  create a table, add an index, or change a schema.
  # Part 3: Trigger phrases (synonyms & natural language)
  Also trigger for "need a migration", "update the schema",
  "add field to model", or any mention of ActiveRecord
  schema changes.
Description Formula

Common Trigger Phrase Patterns

Instructions That Work

Good skill instructions are like good code: specific, unambiguous, and built around concrete examples rather than abstract principles.

Principles of Effective Instructions

1. Be Concrete, Not Abstract

Abstract principles leave room for interpretation. Concrete rules don't.

Follow clean code principles.
Use meaningful names.
Keep methods short.

Place service objects in app/services/.
Name them VerbNoun (e.g. CreateOrder,
  SendInvoice, CancelSubscription).
Each class exposes a single public method
  called .call.
Return a Result object, not raw data.

2. Show, Don't Just Tell

Include a template or minimal example. Claude uses it as a reference, not just inspiration.

## Template

```ruby
# app/services/verb_noun.rb
class VerbNoun
  Result = Struct.new(:success?, :data, :error, keyword_init: true)

  def initialize(arg1:, arg2:)
    @arg1 = arg1
    @arg2 = arg2
  end

  def call
    # main logic here
    Result.new(success?: true, data: result)
  rescue SomeError => e
    Result.new(success?: false, error: e.message)
  end
end
```
SKILL.md — Template Section

3. Specify File Locations

Always say where files go. Claude will default to something reasonable if you don't — but reasonable isn't always right for your project.

## File Locations

- Service objects: `app/services/`
- Specs for services: `spec/services/`
- Shared contexts: `spec/support/shared_contexts/`
- Custom matchers: `spec/support/matchers/`
SKILL.md — File Locations Section

4. State What NOT to Do

Negative constraints are often more valuable than positive instructions because they override Claude's defaults.

## Constraints

- Do NOT use `after_create` callbacks for business logic — use a service instead
- Do NOT put service object logic in the controller
- Do NOT rescue `StandardError` — rescue specific exceptions only
- Do NOT use `ActiveRecord::Base.transaction` inside a service; let the caller decide
SKILL.md — Constraints Section

5. Handle the Common Variations

Think through the most frequent variations of the task and address them explicitly.

## Variations

### If the service needs to call an external API
Inject the HTTP client as a dependency for testability:
```ruby
def initialize(..., http_client: Faraday.new)
```

### If the service is a background job wrapper
Separate the job class from the service class. The job calls the service.
SKILL.md — Variations Section

Recommended Section Order

Progressive Disclosure

Skills have a three-layer loading system. Understanding it lets you write skills that are fast for simple cases and detailed for complex ones — without bloating Claude's context.

The Three Layers in Practice

When to Split Into Reference Files

Split into reference files when your SKILL.md is approaching 400–500 lines, or when you have framework-specific content that only applies in certain cases:

# In SKILL.md body:
## Frontend Integration

If the resource needs Turbo Stream responses, see `references/hotwire.md`.
If using React instead, see `references/react-integration.md`.

# Then the reference files contain the details:
references/
├── hotwire.md       # Full Turbo Stream patterns
└── react-integration.md  # React-specific patterns
Progressive Disclosure Pattern

Organizing Large Reference Files

If a reference file is over 300 lines, add a table of contents at the top. Claude can read the TOC and jump to the relevant section:

# references/hotwire.md

# Hotwire / Turbo Reference

## Table of Contents

1. [Turbo Frames](#turbo-frames) — line 30
2. [Turbo Streams from controllers](#controller-streams) — line 95
3. [Turbo Streams from jobs](#job-streams) — line 150
4. [Stimulus controllers](#stimulus) — line 200
5. [Common patterns](#patterns) — line 260

---

## Turbo Frames
...
references/hotwire.md

Domain Organization Pattern

When a skill covers multiple frameworks or environments, organize reference files by domain — Claude reads only what it needs:

rails-test-generation/
├── SKILL.md              # Main: choose between rspec / minitest
└── references/
    ├── rspec.md           # All RSpec patterns
    ├── minitest.md        # All Minitest patterns
    └── factories.md       # FactoryBot shared reference
Domain Organization

In SKILL.md, include a selection block:

## Test Framework

Check the project for which framework is in use:
- If `spec/` directory exists → RSpec. Read `references/rspec.md`.
- If `test/` directory exists → Minitest. Read `references/minitest.md`.
- If unclear, default to RSpec and ask the user to confirm.
SKILL.md — Framework Selection

Bundled Resources

Beyond the SKILL.md, you can bundle scripts, reference docs, and asset files. These make your skill a self-contained system rather than a set of instructions.

The Three Resource Types

Script Pattern Example

Scripts are powerful for scaffolding workflows. Instead of having Claude generate code step by step, it can run a script:

# scripts/scaffold_resource.sh
#!/bin/bash
# Usage: ./scaffold_resource.sh ResourceName
RESOURCE=$1
LOWER=$(echo "$RESOURCE" | tr '[:upper:]' '[:lower:]')

# Generate model
rails generate model "$RESOURCE"

# Create service directory
mkdir -p "app/services/${LOWER}"

# Create spec directory
mkdir -p "spec/services/${LOWER}"

echo "✓ Scaffolded $RESOURCE"
scripts/scaffold_resource.sh

In SKILL.md, reference it:

## Scaffolding a New Resource

Run the scaffold script to set up the file structure:

```bash
bash scripts/scaffold_resource.sh ResourceName
```

Then follow the convention below to fill in the generated files.
SKILL.md — Script Reference

Asset Template Pattern

# assets/service_object_template.rb.erb
class <%= class_name %>
  Result = Struct.new(:success?, :data, :error, keyword_init: true)

  def initialize(<%= args %>)
<% args.split(',').each do |arg| %>
    @<%= arg.strip %> = <%= arg.strip %>
<% end %>
  end

  def call
    # TODO: implement
    Result.new(success?: true, data: nil)
  end

  private

  attr_reader <%= args.split(',').map { |a| ":#{a.strip}" }.join(', ') %>
end
assets/service_object_template.rb

Reference File Best Practices

• Name files descriptively: rspec-request-specs.md not testing.md
• Add a TOC at the top of any reference file over 300 lines
• Include line numbers in your TOC so Claude can jump to sections
• Write reference files as "here's the pattern" not "here's how Claude should think"
• Include copy-paste-ready code blocks — not prose descriptions of code

Rails-Specific Skills

Rails apps have well-defined layers and conventions that make for excellent skills. Here are the most high-value skills to build for a typical Rails project.

High-Value Rails Skills to Write

A Complete Rails Migration Skill

Here's a fully worked example of a migration skill:

---
name: rails-migrations
description: Write safe, reversible ActiveRecord migrations for Rails
  apps. Use whenever the user asks to add a column, remove a
  column, create a table, add an index, rename a column, or
  change a schema in any way. Also trigger for "update the
  schema", "need a migration", or "add field to model".
---

# Rails Migrations

Generate safe, reversible, zero-downtime-friendly migrations.

## Conventions

- Always use `change` method (reversible) unless you need `up`/`down`
- Name migrations descriptively: `AddStatusToOrders`, not `UpdateOrders`
- Always add `null: false` with a `default:` when adding columns to existing tables

## Adding a Column

```ruby
class AddStatusToOrders < ActiveRecord::Migration[7.1]
  def change
    add_column :orders, :status, :string, null: false, default: "pending"
    add_index :orders, :status
  end
end
```

## Removing a Column

ALWAYS use `ignored_columns` in the model first, deploy, then remove:

```ruby
# Step 1: Add to model (deploy first)
class Order < ApplicationRecord
  self.ignored_columns = ["deprecated_field"]
end

# Step 2: After deploy, create this migration
class RemoveDeprecatedFieldFromOrders < ActiveRecord::Migration[7.1]
  def change
    remove_column :orders, :deprecated_field, :string
  end
end
```

## Constraints

- Never add NOT NULL column without a default to a populated table
- Never use `execute` for data migrations — use a separate Rake task
- Never add an index without `algorithm: :concurrently` on large tables in production
Full Migration SKILL.md

Project-Specific Customization

The best skills are tailored to your specific project. Add a section that captures your project's unique decisions:

## This Project's Conventions

- We use UUIDs as primary keys (`id: :uuid` in all create_table calls)
- All timestamps use `timestamptz` via the `ar-timestamptz` gem
- Soft-delete columns are named `discarded_at` (we use Discard gem)
- Enum columns use `integer` type, not `string`
Project-Specific Section

Common Pitfalls

These are the mistakes that make skills not work — either Claude ignores the skill, or follows it inconsistently. Knowing them in advance will save you a lot of debugging.

Pitfall 1: The Vague Description

Pitfall 2: Principles Instead of Rules

Pitfall 3: No Negative Constraints

Pitfall 4: SKILL.md Too Long

Pitfall 5: Overlapping Skills

Pitfall 6: Writing for Yourself, Not for Claude

Quick Diagnostic Checklist

If your skill isn't working, check these things in order:

• Does the description include specific trigger phrases the user actually says?
• Does the SKILL.md body have concrete templates, not just abstract principles?
• Is there a "Do Not" or "Constraints" section?
• Are all file paths and naming conventions explicitly stated?
• Is the SKILL.md under 500 lines with critical content near the top?
• Is there any ambiguity that would allow multiple interpretations?

Full Examples

Two complete, copy-paste-ready skills you can install immediately or use as templates for your own.

Example 1: Rails Service Objects Skill

---
name: rails-service-objects
description: Generate service objects and operation classes for Rails apps.
  Use this skill whenever the user asks to create a service object,
  extract controller logic into a service, add a business logic class,
  or build an operation/command/interactor. Also trigger for any
  mention of "service layer", "PORO service", "fat controller", or
  "extract this into a class".
---

# Rails Service Objects

Generate single-responsibility service objects for encapsulating
business logic outside of models and controllers.

## Convention

| Attribute | Rule |
|-----------|------|
| Location  | `app/services/` — subdirectory if domain-grouped |
| Naming    | VerbNoun: `CreateOrder`, `SendInvoice`, `CancelSubscription` |
| Interface | Single public method: `.call` or `#call` |
| Return    | `Result` struct, not raw values |
| Spec path | `spec/services/` mirroring `app/services/` |

## Template

```ruby
# app/services/verb_noun.rb
class VerbNoun
  Result = Data.define(:success, :value, :error) do
    def success? = success
    def failure? = !success
  end

  def self.call(...) = new(...).call

  def initialize(required_arg:, optional_arg: nil)
    @required_arg = required_arg
    @optional_arg = optional_arg
  end

  def call
    validate!
    result = perform
    Result.new(success: true, value: result, error: nil)
  rescue MyApp::Error => e
    Result.new(success: false, value: nil, error: e.message)
  end

  private

  attr_reader :required_arg, :optional_arg

  def validate!
    raise MyApp::Error, "required_arg is blank" if required_arg.blank?
  end

  def perform
    # core logic here
  end
end
```

## Usage (in controller)

```ruby
def create
  result = CreateOrder.call(user: current_user, params: order_params)

  if result.success?
    redirect_to result.value, notice: "Order created"
  else
    flash.now[:error] = result.error
    render :new, status: :unprocessable_entity
  end
end
```

## RSpec Template

```ruby
# spec/services/verb_noun_spec.rb
RSpec.describe VerbNoun do
  describe ".call" do
    subject(:result) { described_class.call(**params) }

    let(:params) { { required_arg: "value" } }

    context "when successful" do
      it { is_expected.to be_success }
      it { expect(result.value).to eq(expected_value) }
    end

    context "when required_arg is blank" do
      let(:params) { { required_arg: "" } }
      it { is_expected.to be_failure }
      it { expect(result.error).to include("blank") }
    end
  end
end
```

## Constraints

- Never put service logic in model callbacks or controller actions
- Never rescue `StandardError` — rescue specific exception classes
- Never call `save!` on AR objects inside a service; return data and let
  the caller persist if needed (keeps services testable without DB)
- Never add more than one public method — split into multiple services
rails-service-objects/SKILL.md

Example 2: General Coding Convention Skill

---
name: project-conventions
description: Project-specific coding conventions for this codebase.
  Always use this skill when writing any code for this project —
  it defines the naming, structure, style, and tooling choices
  that override Claude's defaults. Trigger for any code generation,
  refactoring, or editing task in this repository.
---

# Project Conventions

These conventions override Claude's defaults for all code in this repo.

## Ruby Style

- Ruby 3.3+, Rails 7.2+
- Frozen string literals on all new files: `# frozen_string_literal: true`
- Use `Data.define` for value objects (Ruby 3.2+), not `Struct`
- Prefer pattern matching (`case/in`) over chains of `if/elsif`
- `private` methods alphabetically sorted

## Naming

- Models: singular noun (`Order`, `User`)
- Controllers: plural resource (`OrdersController`)
- Services: VerbNoun (`CreateOrder`)
- Jobs: NounVerb + `Job` suffix (`OrderCreatedJob`)
- Concerns: adjective or noun (`Discardable`, `Auditable`)

## Testing

- RSpec only (no Minitest)
- FactoryBot for fixtures — never `Model.create` in specs directly
- All factories in `spec/factories/` — one file per model
- No `let!` — use `let` and `before` instead
- Descriptive `it` blocks: use present tense ("returns X", not "should return X")

## Tooling

- Rubocop with standard gem — never disable cops inline
- Brakeman for security — fix all warnings before merging
- Bundler Audit in CI

## What NOT to Do

- No `puts` or `p` — use `Rails.logger`
- No `rescue Exception` — ever
- No inline SQL — use AR query interface or Arel
- No `Time.now` — use `Time.current` (timezone-aware)
- No `Date.today` — use `Date.current`
project-conventions/SKILL.md

Testing & Improving Skills

A skill draft is just a hypothesis. The real work is figuring out where it breaks down and tightening the instructions until Claude consistently does exactly what you want.

How to Test a Skill

Diagnosing Failures

The Improvement Loop

# Skill improvement is a loop, not a one-shot

while skill_not_good_enough:
  run_test_prompts(skill)
  failures = identify_failures()

  if failures.include?(:trigger_failure):
    improve_description()
  
  if failures.include?(:wrong_output):
    improve_instructions()
    add_constraints()
    clarify_template()
  
  if skill.body.length > 500:
    extract_to_reference_files()
Pseudocode

Evolving Skills Over Time

Your skill should evolve as your codebase and preferences evolve. Good triggers to update a skill:

• You catch Claude doing something wrong that it keeps repeating
• You make a project-wide refactor that changes a convention
• You upgrade a gem and the API or patterns change
• A teammate says "Claude always generates the tests wrong"
• You add a new layer to your architecture (e.g., start using presenters)

Quick Reference

Everything you need on one page. Bookmark this section and use it while writing or reviewing skills.

SKILL.md Checklist

• Description: 60–120 words, includes what it does + when to trigger + synonym phrases
• Name: Stable kebab-case identifier, won't change
• Intro: One sentence saying what this skill produces
• Convention section: Explicit naming, file path, structure rules
• Template: Copy-paste-ready code block (for code skills)
• Constraints: At least 3 "never do X" rules
• Edge cases: Variations section for common alternatives
• Length: Under 500 lines, critical content in first 200

Description Formula

description: [WHAT it does in one clear sentence.]
  [WHEN to trigger: specific task types and contexts.]
  [ALSO trigger for: synonym phrases and natural language variants.]
Formula

Instruction Writing Rules

File Structure Reference

my-skill/
├── SKILL.md               # Required. Main instructions.
├── scripts/               # Optional. Runnable shell/ruby scripts.
│   └── setup.sh
├── references/            # Optional. Large docs Claude reads on demand.
│   ├── framework-a.md
│   └── framework-b.md
└── assets/                # Optional. Template files, boilerplate.
    └── template.rb
Structure

Trigger Failure Diagnosis

Top Rails Skills to Write

rails-service-objects rails-migrations rails-rspec-patterns rails-factories hotwire-turbo stimulus-controllers sidekiq-jobs pundit-policies project-conventions

The Golden Rules