rails-agent-kit 0.1.0 → 0.2.0

data/lib/rails_agent_kit/skill_installer.rb

@@ -3,21 +3,72 @@
 require "fileutils"
 
 module RailsAgentKit
-  # Copies the agent skills bundled with the gem (skills/<name>/SKILL.md) into a Rails app,
-  # e.g. <root>/.cursor/skills/<name>/SKILL.md for Cursor.
+  # Installs the agent skills bundled with the gem (skills/<name>/SKILL.md) into a Rails app.
+  #
+  # Agents with skill folders get a copy of each SKILL.md:
+  #
+  #   cursor  -> .cursor/skills/<name>/SKILL.md
+  #   claude  -> .claude/skills/<name>/SKILL.md
+  #
+  # Agents that read a single instructions file get the skills rendered into a managed block between
+  # MARKER_START and MARKER_END. Content outside the block is never touched:
+  #
+  #   codex   -> AGENTS.md (also read by Cursor, Copilot, Windsurf, Zed and others)
+  #   copilot -> .github/copilot-instructions.md
+  #   gemini  -> GEMINI.md
   class SkillInstaller
     SKILLS_DIR = File.expand_path("../../skills", __dir__)
-    TARGETS = {
+    SKILL_DIRS = {
       "cursor" => ".cursor/skills",
       "claude" => ".claude/skills"
     }.freeze
+    INSTRUCTION_FILES = {
+      "codex" => "AGENTS.md",
+      "copilot" => ".github/copilot-instructions.md",
+      "gemini" => "GEMINI.md"
+    }.freeze
+    TARGETS = SKILL_DIRS.merge(INSTRUCTION_FILES).freeze
+    MARKER_START = "<!-- rails-agent-kit:start -->"
+    MARKER_END = "<!-- rails-agent-kit:end -->"
 
-    Result = Struct.new(:skill, :path, :status, keyword_init: true)
+    Result = Struct.new(:skill, :path, :status, :message, keyword_init: true)
 
     def self.available_skills
       Dir.glob(File.join(SKILLS_DIR, "*", "SKILL.md")).map { |f| File.basename(File.dirname(f)) }.sort
     end
 
+    # The managed block for instruction-file agents: the skills' bodies without front matter, with every
+    # heading one level deeper so they nest under the file's own top-level heading.
+    def self.render_block(skills)
+      bodies = skills.map { |name| demote_headings(strip_front_matter(File.read(skill_source(name)))).strip }
+      [
+        MARKER_START,
+        "<!-- Generated by `rails-agent-kit install-skills`. Edits inside this block are replaced on the next run. -->",
+        "",
+        bodies.join("\n\n"),
+        MARKER_END
+      ].join("\n") + "\n"
+    end
+
+    def self.skill_source(name)
+      source = File.join(SKILLS_DIR, name, "SKILL.md")
+      raise Error, "unknown skill #{name.inspect} (available: #{available_skills.join(', ')})" unless File.file?(source)
+
+      source
+    end
+
+    def self.strip_front_matter(text)
+      text.sub(/\A---\s*\n.*?\n---\s*\n/m, "")
+    end
+
+    def self.demote_headings(text)
+      in_fence = false
+      text.lines.map do |line|
+        in_fence = !in_fence if line.start_with?("```", "~~~")
+        !in_fence && line.match?(/\A\#{1,5} /) ? "##{line}" : line
+      end.join
+    end
+
     def initialize(root, agent: "cursor", force: false)
       @root = File.expand_path(root)
       @agent = agent.to_s
@@ -25,23 +76,32 @@ module RailsAgentKit
       raise Error, "unknown agent #{@agent.inspect} (supported: #{TARGETS.keys.join(', ')})" unless TARGETS.key?(@agent)
     end
 
-    # Installs the named skills (default: all bundled skills). Existing files that differ are left
-    # untouched unless force: true. Returns one Result per skill with status :created, :updated,
-    # :unchanged or :skipped.
+    # Installs the named skills (default: all bundled skills). Returns one Result per written path with status
+    # :created, :added (block appended to an existing file), :updated, :unchanged or :skipped. A skill copy you
+    # have edited is skipped unless force: true; a managed block is always brought up to date.
     def install(skills = self.class.available_skills)
-      skills.map do |name|
-        source = File.join(SKILLS_DIR, name, "SKILL.md")
-        raise Error, "unknown skill #{name.inspect} (available: #{self.class.available_skills.join(', ')})" unless File.file?(source)
+      run(skills, write: true)
+    end
 
-        install_one(name, source)
-      end
+    # Same statuses as #install, without writing anything.
+    def plan(skills = self.class.available_skills)
+      run(skills, write: false)
     end
 
     private
 
-    def install_one(name, source)
-      dest = File.join(@root, TARGETS.fetch(@agent), name, "SKILL.md")
-      content = File.read(source)
+    def run(skills, write:)
+      skills.each { |name| self.class.skill_source(name) }
+      if INSTRUCTION_FILES.key?(@agent)
+        [install_block(skills, write: write)]
+      else
+        skills.map { |name| install_skill(name, write: write) }
+      end
+    end
+
+    def install_skill(name, write:)
+      dest = File.join(@root, SKILL_DIRS.fetch(@agent), name, "SKILL.md")
+      content = File.read(self.class.skill_source(name))
       status =
         if !File.exist?(dest) then :created
         elsif File.read(dest) == content then :unchanged
@@ -49,11 +109,37 @@ module RailsAgentKit
         else :skipped
         end
 
-      if %i[created updated].include?(status)
-        FileUtils.mkdir_p(File.dirname(dest))
-        File.write(dest, content)
-      end
+      write_file(dest, content) if write && %i[created updated].include?(status)
       Result.new(skill: name, path: dest, status: status)
     end
+
+    def install_block(skills, write:)
+      dest = File.join(@root, INSTRUCTION_FILES.fetch(@agent))
+      block = self.class.render_block(skills)
+      result = ->(status, message = nil) { Result.new(skill: skills.join(", "), path: dest, status: status, message: message) }
+      return result.call(:created).tap { write_file(dest, block) if write } unless File.exist?(dest)
+
+      current = File.read(dest)
+      start = current.index(MARKER_START)
+      finish = start && current.index(MARKER_END, start)
+      if start.nil? && !current.include?(MARKER_END)
+        separator = current.empty? || current.end_with?("\n\n") ? "" : (current.end_with?("\n") ? "\n" : "\n\n")
+        write_file(dest, current + separator + block) if write
+        return result.call(:added)
+      end
+      return result.call(:skipped, "found an unmatched rails-agent-kit marker; fix or remove it") if finish.nil?
+
+      stop = finish + MARKER_END.length
+      stop += 1 if current[stop] == "\n"
+      return result.call(:unchanged) if current[start...stop] == block
+
+      write_file(dest, current[0...start] + block + current[stop..]) if write
+      result.call(:updated)
+    end
+
+    def write_file(dest, content)
+      FileUtils.mkdir_p(File.dirname(dest))
+      File.write(dest, content)
+    end
   end
 end

data/lib/rails_agent_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAgentKit
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/rails_agent_kit.rb

@@ -5,8 +5,10 @@ require_relative "rails_agent_kit/schema_parser"
 require_relative "rails_agent_kit/structure_sql_parser"
 require_relative "rails_agent_kit/schema_inspector"
 require_relative "rails_agent_kit/routes_parser"
+require_relative "rails_agent_kit/ruby_env"
 require_relative "rails_agent_kit/routes_inspector"
 require_relative "rails_agent_kit/skill_installer"
+require_relative "rails_agent_kit/client_config"
 
 # Gives coding agents ground truth about a Rails app (schema, routes) over MCP.
 module RailsAgentKit

data/skills/rails-8-conventions/SKILL.md

@@ -20,8 +20,9 @@ change the code the way this app already does things.
 
 ## 1. Check the facts before you edit
 
-- **Schema:** call the `rails_schema` MCP tool (pass `table:` to get one table) before
-  you write a model attribute, query, validation, fixture or migration. Without the
+- **Schema:** call the `rails_schema` MCP tool before you write a model attribute, query,
+  validation, fixture or migration. With no arguments it lists the tables; pass `table:`
+  (one name or an array) for their columns, or `search:` to find a column by name. Without the
   tool, read `db/schema.rb` (or `db/structure.sql`). Never guess a column name, type,
   nullability or default.
 - **Routes:** call the `rails_routes` MCP tool (pass `filter:`) before you use a

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-agent-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrii Furmanets
@@ -23,10 +23,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
-description: rails-agent-kit is a small Model Context Protocol (stdio) server. It
-  exposes a Rails app's database schema (parsed from db/schema.rb without booting
-  the app) and its routes to coding agents such as Cursor and Claude Code, and ships
-  a Rails 8 conventions skill for Cursor/Claude (installed with `rails-agent-kit install-skills`).
+description: rails-agent-kit is a read-only Model Context Protocol (stdio) server
+  for Rails apps. rails_schema returns tables, columns, indexes and foreign keys parsed
+  statically from db/schema.rb (without booting the app); rails_routes returns every
+  route from `bin/rails routes --expanded`. It also ships a Rails 8 conventions skill
+  for Cursor and Claude Code, installed with `rails-agent-kit install-skills`.
 executables:
 - rails-agent-kit
 extensions: []
@@ -37,8 +38,10 @@ files:
 - README.md
 - exe/rails-agent-kit
 - lib/rails_agent_kit.rb
+- lib/rails_agent_kit/client_config.rb
 - lib/rails_agent_kit/routes_inspector.rb
 - lib/rails_agent_kit/routes_parser.rb
+- lib/rails_agent_kit/ruby_env.rb
 - lib/rails_agent_kit/schema_inspector.rb
 - lib/rails_agent_kit/schema_parser.rb
 - lib/rails_agent_kit/server.rb
@@ -51,8 +54,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/afurm/rails-agent-kit
-  source_code_uri: https://github.com/afurm/rails-agent-kit
+  source_code_uri: https://github.com/afurm/rails-agent-kit/tree/main
   changelog_uri: https://github.com/afurm/rails-agent-kit/blob/main/CHANGELOG.md
+  documentation_uri: https://afurm.github.io/rails-agent-kit/
   bug_tracker_uri: https://github.com/afurm/rails-agent-kit/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -69,8 +73,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.20
 specification_version: 4
-summary: MCP server and agent skills that give coding agents ground truth about a
-  Rails app's schema and routes.
+summary: MCP server and Rails 8 agent skill that give coding agents (Cursor, Claude
+  Code, Codex) ground truth about your Rails app's schema and routes.
 test_files: []