Calling Skills and Workflows

Rails Agent Skills can be invoked in three distinct ways depending on the environment, the user's intent, and the level of autonomy desired. Understanding the syntax and context for each method ensures you get the most out of your AI coding assistant.

The 3 Execution Contexts

1. MCP (use_skill)

When the repository is connected to an MCP (Model Context Protocol) client (like Claude Desktop, Cursor, or Windsurf), the AI agent has access to the library's metadata.

Syntax: The LLM automatically invokes the use_skill(skill_name) tool based on the user's prompt. Example User Prompt: "Please review this pull request for security vulnerabilities." Agent Action: Autonomously loads security-check and code-review.

When to use: Use this method when you want the agent to autonomously figure out which skills apply to your broad request. It minimizes the cognitive load on the developer.

2. Chat Commands (@ or /)

In environments that support explicit context injection (like Cursor, Windsurf, or Gemini CLI), developers can force the agent to use a specific skill immediately.

Syntax:

• Cursor / Windsurf: @skill-name (e.g., @write-tests Can you add coverage for the new order model?)
• Gemini CLI: /activate_skill skill-name or /skill-name

When to use: Use this when you know exactly which workflow you want to follow and want to bypass the autonomous discovery phase. It is highly effective for enforcing strict constraints (like the "Tests Gate Implementation" rule) on specific tasks.

3. CLI (gh skill / tessl / skills.sh)

For manual installation, version pinning, or evaluation, you can interact with the skills directly via the terminal.

Syntax: Installing via GitHub CLI:

# Install a specific skill for the current project
gh skill install igmarin/rails-agent-skills code-review --scope project

Installing via skills.sh:

# Add the entire library to your workspace
npx skills add igmarin/rails-agent-skills

Evaluating via Tessl:

# Run evaluations to measure skill quality
tessl eval run .

When to use: Use the CLI method when setting up a new project, configuring CI/CD pipelines, or when you need to pin your workspace to a specific release tag of a skill for reproducible results.

Using Workflows

Workflows are orchestrated multi-step processes that chain multiple skills together. They are the primary way to execute complex Rails development tasks with built-in quality gates and TDD enforcement.

MCP Workflow Usage

When connected via MCP, workflows are discovered and executed using two dedicated tools:

Discover available workflows:

list_workflows

Returns metadata for all 9 workflows: tdd, quality, review, setup, engine, bug-fix, graphql, migration, background-job

Load and execute a specific workflow:

use_workflow(workflow_name: "tdd")

Returns the full workflow instructions with phases, hard gates, and skill chaining

Example MCP interaction:

• User: "I need to implement a new feature following TDD best practices"
• Agent: Calls list_workflows → identifies tdd workflow → calls use_workflow("tdd") → executes the full TDD cycle with gates

Chat Command Workflow Usage

In environments that support chat commands, you can invoke workflows directly:

Cursor / Windsurf:

@tdd Implement the user authentication feature

Gemini CLI:

/activate_workflow tdd

Available Workflows

Workflow Advantages

Compared to ad-hoc skill chaining, workflows provide:

• Hard Gates: Enforced checkpoints (e.g., "tests must pass before implementation")
• TDD Enforcement: Built-in test-first discipline for code changes
• Consistent Structure: Standardized phases and error recovery
• Integration Points: Clear predecessor/successor relationships
• Production Readiness: Security checks, monitoring, and deployment guidance