Published 2025-11-23.
Time to read: 2 minutes.
jekyll collection.
After installing mini-agent as described in MiniMax Mini-Agent Review I was able to use it with great success to fix a bug in a Jekyll plugin that I was working on.
Overview
After several sessions in which I got a feeling for the behavior of mini-agent, I decided to try a small bug fix that involves two projects. This is something I had originally tried to do with Google Gemini Code Assist, but learned that Google Gemini Code Assist cannot handle more than one code base at a time.
I always build systems from components. Each component gets its own Git project. An agentic assistant that cannot deal with more than a single project at once is nearly useless to me.
I have published dozens of Ruby gems for Jekyll Plugins using my Jekyll Plugin Support gem. The Flexible Include plugin is one of my most popular plugins. I was implementing a new feature, and realized that some logic should be moved from the framework to the plugin.
The instructions I gave mini-agent are shown in the next section.
These LLM directives are now part of the Jekyll Plugin Support Git project. Everyone who clones the framework or works on a plugin built with that framework can use the directives with any agentic programming agent to create or maintain these projects.
Ruby Gems For Jekyll Plugin
# Jekyll Plugin Support Instructions for Claude ## General Instructions - Read `.claude/RUBY_STANDARDS.md` in this directory so you can learn about Ruby coding instructions. - Do not use emojis in user dialog or documentation. - Do not use superlatives; instead, be strictly factual. - Do not ask the user several questions at once. Instead, make a list of questions and ask your questions one at a time. - Make no assumptions. Ask the user about every ambiguity or corner case, and suggest a better way if there is one. Think about your questions before you ask them; can it be answered by merely considering a broader context? If so, make that a provisional assumption and ask for confirmation. - If you need to write documentation, place the file in the `docs/` directory. - Before running every git command, check if `.git/index.lock` exists, and delete it using `sudo` if so. - Git projects have environment variables that point to their directories. Some examples: - `$jekyll_plugin_support` points to the directory containing the `jekyll_plugin_support` Git project. - `$jekyll_href` points to the directory containing the `jekyll_href` Git project that defines the `href` plugin. - `$jekyll_pre` points to the directory containing the `jekyll_pre` Git project that defines the `pre` plugin. - `$jekyll_img` points to the directory containing the `jekyll_img` Git project that defines the `img` plugin. - `$jekyll_flexible_include_plugin` points to the `jekyll_flexible_include_plugin` Git project that contains the directory containing the `flexible_include` plugin. ## Requirements for Done The following must be completed before your work can be considered to be done. - Update documentation with changes - Unit tests must pass - Linters for all languages (bash, Ruby, Markdown, etc) must succeed. - Unit tests must pass. - Update `README.md` for user-visible changes only. - Update `CHANGES.md` for programmer-visible changes, described at a high level. - Update `.claude/PROGRESS.md`. - Only then `git push` with a message and commit. ## DO THIS NOW Read `.claude/FUTURE.md` and execute instructions in the following section: Rework Windows Environment Variable Expansion
# Future Work Do not perform any of the following without specific authorization. ## Rework Windows Environment Variable Expansion Many shells, for example Bash, denote environment variable references (env vars) by prefixing them with a dollar sign ($). Windows environment variables are denoted differently, by enclosing them within percents (%). In JPS, the current implementation of environment expansion is defined in the `JekyllPluginHelper.expand_env` method in `$jekyll_plugin_support/lib/helper/jekyll_plugin_helper_class.rb`. This method currently calls `JekyllPluginHelper.expand_env`, which in turn calls `JekyllPluginHelper.env_var_expand_bash` and `JekyllPluginHelper.env_var_expand_windows`. This is problematic because websites often contain text strings that contain pairs of percents that should not be expanded because they do not correspond to environment variables (for example "blah%some_text%more text"). To correct the problem, `expand_env` should never call `env_var_expand_windows`, and should instead merely return the result of calling `env_var_expand_bash`. This means that the `use_wslvar` parameter is not required by this method or the methods that it calls, and the method signatures should be simplified. `JekyllPluginHelper.env_var_expand_windows` will be called by JPS plugins when required, so that method it must remain intact. Currently the only Jekyll plugin that needs to call `JekyllPluginHelper.env_var_expand_windows` is `jekyll_flexible_include_plugin`. That plugin only needs to call `JekyllPluginHelper.env_var_expand_windows` to expand the `file` parameter, exactly as shown in `$jekyll_flexible_include_plugin/demo/index.html`. Modify `$jekyll_flexible_include_plugin/lib/flexible_include_private_methods.rb` so the `@filename` parameter is expanded using both `JekyllPluginHelper.env_var_expand_bash` and `JekyllPluginHelper.env_var_expand_windows`. I already updated `CHANGELOG.md` so you do not have to. Describe your plan and obtain approval before starting.
# Progress
# Ruby Programming Standards
Jekyll is a Ruby gem that creates static websites.
This project (`jekyll_plugin_support`) is a framework for writing and testing
[Jekyll](https://jekyllrb.com/) plugins in the Ruby language. These plugins
share common coding standards and debugging techniques. We shall refer to
`jekyll_plugin_support` as `JPS` for convenience, and plugins created from the
JPS framework as `JPS plugins`.
## General
- Write using Ruby 3.4.7 features and recommended syntax.
- Follow the existing coding style.
- Use multiline strings whenever possible using squiggly heredocs (`<<~IDENTIFIER`).
- Before making any changes, tell the user a high-level explanation
- If requested, show detailed changes.
- Proceed after the user approves the changes.
## Comments
- Preserve existing comments and formatting.
- Only write new comments when they are non-obvious.
- Assume the reader knows the Ruby language, so do not explain common Ruby
coding techniques.
- Assume the reader is new to writing Jekyll plugins and is unfamiliar with
`jekyll_plugin_support`.
## Unit Tests
- Write unit tests using RSpec for non-trivial functionality.
See the `spec` subdirectory for examples of existing tests.
- Configuration for unit tests is provided in the top-level `_config.yml` in this project.
## Demo Project
Many features cannot be easily tested using RSpec. However, all features should
be testable by making Jekyll web pages in the Jekyll website in the `demo`
subdirectory and running the demo.
- Use the scripts in the `bin/` directory to test functionality in a live setup.
- All Jekyll plugins based on `jekyll_plugin_support` should include a `demo`
subdirectory.
- Configuration for the `demo` Jekyll website is provided in `_config.yml` in
that subdirectory.
- The `demo` project in the `jekyll_plugin_support` project contains examples of
how important JPS plugins are used.
### Demo Project Configuration
- The `Gemfile` in the `demo/` subdirectory can be used for debugging plugins
based on `jekyll_plugin_support`.
- Each of the `gem` lines can include an optional `path` argument, like
`path: jekyll_flexible_include`. Here is an example:
```ruby
jekyll_flexible_include = ENV.fetch('jekyll_flexible_include', nil)
group :jekyll_plugins do
gem 'jekyll_flexible_include', path: jekyll_flexible_include
end
```
Do It Now
Now all I had to type was:
Read and execute .claude/CLAUDE.md
After carefully preparing several very detailed files, the work was done within 20 minutes. I did some housework while waiting. The new release was solid. Life was good.
The time I spent preparing for this simple bug fix will benefit myself and others every time that another change needs to be made.
