How to Refactor a Complex Blog Review Prompt into Reusable AI Agents
Technical writers and ESL professionals often rely on complex prompts to polish our work. However, as prompts grow into monolithic walls of text, they become brittle, hard to debug, and expensive to run. Modularity addresses this challenge.
In this post, I transition from a single Custom Command to a modular, portable Gemini CLI extension implemented as a set of specialized Agent Skills.
Prerequisites
Before we begin, ensure you have the following:
- Install the gemini-cli.
- Create a Google AI Studio API Key or a Vertex AI Credential.
- Ensure you have access to a terminal (macOS, Linux, or WSL).
Setting Up the Environment
Install the Gemini CLI globally.
npm install -g @google/gemini-cli
To access your extension and the API key globally, create a .env file in the ~/.gemini global workspace, and add the API key to the .env file as follows:
# Your Google AI Studio API Key
GEMINI_API_KEY=<Gemini API Key>
I use the ~/.gemini path, which is standard for macOS/Linux systems. The audience is either using or is familiar with a Unix-like environment.
Gemini CLI automatically loads variables from the first .env file it finds, searching up from the current directory, then in ~/.gemini/.env or ~/.env.
When the CLI loads the GEMINI_API_KEY from the .gemini/.env file, it works in projects automatically. Moreover, it acts as a single source of truth for key rotation. When the key expires, users only need to update a single file, rather than hunting down multiple copies scattered across projects.
Comparison between Custom Commands and Agent Skills
While both Agent Skills and Custom Commands add functionality to the Gemini CLI, they serve fundamentally different architectural roles. A Custom Command is a shortcut that can run in a terminal or in a Gemini CLI chat. On the other hand, an Agent Skill acts as a plugin or a domain expert to provide expertise to the AI model.
There are four key differences between Custom Commands and Agent Skills.
| Feature | Custom Command | Agent Skill |
|---|---|---|
| Activation | Explicit (Slash command) | Automatic (Model-decided) |
| Structure | Single .toml file |
Directory with SKILL.md & assets |
| Context | Prompt loaded immediately | Instructions loaded on-demand |
| Use Case | One-shot transformation | Multi-step / Stateful workflow |
Custom commands are slash commands that users must type explicitly into the terminal. The AI model does not use them unless the user explicitly requests them. In contrast, the model analyzes a user prompt to identify the skill gap and activates a skill based on the skill description. This relies on Gemini's function calling capabilities to autonomously select the right tool.
A Custom Command is a
TOMLfile containing a description and a prompt. When a user places a command in thecommandsfolder of the global.geminifolder, it is available after restarting the Gemini CLI. An Agent Skill is a self-contained directory with aSKILL.mdMarkdown file, instructions, metadata, and external assets such as scripts, templates, or example data. When the directory is placed in theskillsfolder of the global.geminifolder, it is available after restart.When a user runs a Custom Command, the model loads the prompt from the
TOMLfile into its current context. The CLI loads the name and description of all the skills into the model's context. This ensures the model is aware of the tools without consuming context tokens on their instructions until they are actually invoked. The instructions and external assets are loaded into the context window when the model explicitly calls a specific skill. This allows users to have hundreds of specialized skills without exhausting the token limit.A Custom Command is primarily used for one-shot transformations. Users provide the inputs and the Custom Command calls the prompt to generate the results. An Agent Skill is designed for a multi-step procedural workflow. A skill can define a complex thought process or a series of actions to solve a complex problem. It represents a stateful capability rather than a text shortcut.
Understanding the Architecture
- Custom Command Architecture
In the blog-review.toml file, I initially defined the description and a prompt that instructs the model to read a blog post and audit the content against the nine focus areas.
- Modular Agent Skills
I extracted each focus area into a separate Agent Skill that could be executed individually or as part of the Custom Command.
- Portable CLI Extension Packaging
I created a new CLI extension project to package the Custom Command and skills. Then, I installed the extension in the Gemini CLI.
The Starting Point: A Monolithic Custom Command
I started with a single, exhaustive prompt that detected every linguistic error in a Markdown file.
description = "Comprehensive Markdown Prose Auditor: Scans for grammar, syntax, tone, and technical clarity with list-based reporting and a summary table."
prompt = """
You are a Senior Technical Copyeditor. Your goal is to identify and provide specific fixes for linguistic and structural errors in Markdown content without rewriting the entire document.
### YOUR MISSION:
Perform a word-by-word audit of the input. Group all identified issues by their category so the user can review them systematically.
**Focus Areas:**
1. **Grammar & Syntax:** Subject-verb agreement, tense consistency, and prepositions.
2. **Active Voice:** Converting passive descriptions into direct, active instructions.
### CONSTRAINTS:
- **DO NOT** output the full polished text.
- **DO NOT** report errors found inside code blocks (<triple ticks>).
- **FORMAT:** Use a **List** for the audit details (for console readability) and a **Table** for the final summary.
- **LOCATION:** Specify the nearest Heading or Paragraph number for every find.
### CONTENT TO AUDIT:
<content>
{{args}}
</content>
### OUTPUT FORMAT:
#### 🔬 LINGUISTIC AUDIT DETAILS
### [Category Name]
- **Location:** [Heading/Paragraph]
- **Original:** "..."
- **Fixed:** "..."
- **Rationale:** [Brief explanation of the fix]
---
#### 📊 AUDIT SUMMARY
| Category | Issues Found |
| :--- | :--- |
| 1. Grammar & Syntax | [Count] |
| 2. Active Voice | [Count] |
| **TOTAL** | **[Sum]** |
"""
{{args}} is the placeholder for the user's input file or text.
I copied blog-review.toml to ~/.gemini/commands.
mkdir -p ~/.gemini/commands
cp blog-review.toml ~/.gemini/commands
Then, I started gemini to verify the blog-review command's availability.
gemini
/blog-review
How to Execute the Command
I created a dummy file named test_agent_skills.md containing intentional errors to test the system. To execute this command in the standard CLI, I passed it as an argument:
# In a terminal
gemini /blog-review @test_agent_skills.md
Or, in the Gemini CLI chat:
gemini
/blog-review @test_agent_skills.md
The Custom Command identified 25 issues and displayed the results in the console. While handling fewer than 10 issues was manageable, the 25 identified issues exceeded a viable threshold.
To fix this, I needed to decouple the detection logic. I decided to build specialized Agents for each category.
Instead of listing every issue, I focused on one area and fixed all related issues. Using Agent Skills established the modular architecture. For example, I used natural language to identify grammar and syntax errors in a blog post.
In the following sections, I created grammar-syntax-reviewer, missing-article-reviewer, lexical-precision-reviewer, technical-punctuation-reviewer, and active-voice-reviewer skills.
Build the Skill Suite
To improve accuracy, extract the grammar logic into a specialized "Agent Skill."
I created a test-project/skills folder recursively.
mkdir -p test-project/skills
I created a file named SKILL.md in the test-project/skills/grammar-syntax-reviewer directory.
The Markdown file has the following structure:
- YAML Metadata
- PERSONA
- REVIEW PROTOCOL
- STRATEGIC RULES
- OUTPUT FORMAT
Below is the full content of SKILL.md of grammar-syntax-reviewer skill:
Grammar & Syntax Reviewer (7-Category Exhaustive Edition)
---
name: grammar-syntax-reviewer
description: A high-precision editorial skill focused on subject-verb agreement, tense consistency, prepositional accuracy, and structural integrity in technical writing.
---
# Grammar & Syntax Reviewer (7-Category Exhaustive Edition)
## PERSONA
You are a Senior Technical Copyeditor and ESL Writing Coach. You possess an obsessive eye for the mechanical "gears" of the English language. Your goal as a Grammar & Syntax Reviewer is to ensure that every sentence follows the formal rules of English grammar to provide maximum clarity for a global audience, with special attention to technical nuances.
## REVIEW PROTOCOL
Execute seven distinct passes over the text and group findings into these categories:
1. **CATEGORY 1: Subject-Verb Agreement (including Intervening Phrases)**
- Target: Verbs that do not match their subjects, especially when separated by long phrases (e.g., "The list of all available API endpoints are" vs "The list... is").
[Other categories omitted for brevity]
## STRATEGIC RULES
- **No Omissions:** Identify EVERY instance. If a document has 20 errors, list all 20.
- **Searchability Priority:** Provide the nearest **Heading** and the **Full Sentence (Verbatim)** so the user can use Ctrl+F.
- **Code-Adjacent Logic:** Pay extra attention to the grammar of sentences that wrap around inline code backticks (e.g., "Using the `GET` methods" where it should be "method").
- **Code Immunity:** Ignore everything inside triple backticks (<triple ticks>).
## OUTPUT FORMAT
### 🔬 EXHAUSTIVE GRAMMAR & SYNTAX REVIEW
### Category 1: Subject-Verb Agreement
- **Location:** [Heading]
- **Search String:** "[Full sentence containing the error]"
- **Fixed:** "[The corrected full sentence]"
- **Rationale:** [Briefly explain the rule, e.g., "The collective noun 'group' is singular and requires the verb 'is'."]
---
### [Continue for other Categories...]
---
#### 📊 GRAMMAR & SYNTAX REVIEW SUMMARY
| Category | Issues Found |
| :--- | :--- |
| 1. Subject-Verb Agreement | [Count] |
| **TOTAL ERRORS** | **[Sum]** |
The other skills are similar and are omitted for brevity. The full content of the skills can be found in: Custom Blog Review Agent Skills
Active Voice Reviewer
The Active Voice Reviewer skill is designed to ensure technical content is direct and authoritative. Create skills/active-voice-reviewer/SKILL.md:
---
name: active-voice-reviewer
description: A high-precision editorial skill designed to eliminate passive voice, weak 'to-be' constructions, and nominalizations in technical prose.
---
# Active Voice Reviewer
## PERSONA
You are a Senior Technical Copyeditor specializing in Instructional Clarity. Your goal is to eliminate passive voice, weak "to-be" constructions, and indirect phrasing to make technical prose direct, authoritative, and easier to follow.
## REVIEW PROTOCOL
1. **CATEGORY 1: Formal Passive Voice**
- Target: "To-be" verb + Past Participle (e.g., "is clicked by").
## STRATEGIC RULES
- **No Omissions:** Identify EVERY instance. If a document has 50 issues, list all 50.
## OUTPUT FORMAT
### ⚡ EXHAUSTIVE ACTIVE VOICE AUDIT
### Category 1: Formal Passive Voice
- **Location:** ## Authentication Flow
- **Search String:** "The security token is generated by the middleware layer after the request arrives."
- **Fixed (Active):** "The middleware layer generates the security token after the request arrives."
- **Rationale:** The actor (middleware layer) was placed at the end of the sentence. Moving it to the subject position makes the sentence more direct.
[Other categories omitted for brevity]
#### 📊 ACTIVE VOICE SUMMARY
| Category | Issues Found |
| :--- | :--- |
| 1. Formal Passive Voice | [Count] |
| **TOTAL IMPROVEMENTS** | **[Sum]** |
Run Skills in the Gemini CLI Chat
The skills folder did not exist in ~/.gemini, so I created the folder and copied all the skills to it.
mkdir -p ~/.gemini/skills
cp -r ~/test-project/skills/* ~/.gemini/skills
To use these skills interactively, start the chat REPL:
gemini
Enable the experimental Agent Skills in the CLI.
/settings
The CLI displays a settings screen featuring a search filter to narrow down the settings.
Users input "Agent" in the search filter and scroll the list until "Enable Agent Skills" is visible. Users can set the flag to true and apply the changes to User Settings.
Restart gemini to enable the Agent Skills.
Inside the chat, manage your skills:
-
/skills— List all detected skills. -
/skills enable <skill>— Activate a specific skill. -
/skills disable <skill-name>— Deactivate a specific skill. -
/skills reload— Refresh the list if you've added new files.
I instructed the CLI to identify active-voice issues in the blog post. The AI model used the active-voice-reviewer skill to find all issues.
Find the active voice issues in @test_agent_skills.md
The CLI prompted me to activate the skill.
✓ Activate Skill "active-voice-reviewer": A high-precision editorial skill designed to eliminate passive voice, weak 'to-be' constructions, and nom… │
│ │
│ Skill active-voice-reviewer activated. Resources loaded from ~/.gemini/skills/active-voice-reviewer: │
│ │
│ Showing up to 200 items (files + folders). │
│ │
│ ~/.gemini/skills/active-voice-reviewer/ │
│ └───SKILL.md
The CLI displayed the issues and the skill summary.
Category 1: Formal Passive Voice
- Location: ## Demo Overview
- Search String: "the Google Search Tool is used."
- Fixed (Active): "the model uses the Google Search Tool."
- Rationale: The original sentence obscures the actor (the model).
---
Category 2: Hidden Actors (Agentless Passive)
- Location: ## Introduction
- Search String: "and the response JSON schema is provided"
- Fixed (Active): "and you provide the response JSON schema"
- Rationale: The original implies the schema appears by magic.
---
Category 3: Weak "To-Be" Wind-ups (Deadwood)
- Location: ## Lessons Learned (4. Valid URI...)
- Search String: "The solution was to provide instructions for categorizing"
- Fixed (Active): "I solved this by instructing the model to categorize"
- Rationale: "The solution was to" is a weak, noun-heavy wind-up. "I solved this by" is dynamic.
---
Category 4: Nominalizations (Smothered Verbs)
- Location: ## Demo Overview
- Search String: "Name verification is performed before data retrieval."
- Fixed (Active): "The script verifies the name before retrieving data."
- Rationale: "Verification" and "retrieval" are smothered verbs. "Verifies" and "retrieving" restore the energy.
- Location: ## Lessons Learned (4. Valid URI...)
- Search String: "The solution was to provide instructions for categorizing"
- Fixed (Active): "I solved this by instructing the model to categorize"
- Rationale: "Provide instructions" is a weak nominalization of "instruct".
---
Category 5: Modal Hesitation (Soft Commands)
- Location: ## Architecture
- Search String: "it can access an external system"
- Fixed (Active): "it accesses an external system"
- Rationale: "Can access" implies capability; "accesses" describes what it actually does in this architecture.
---
📊 ACTIVE VOICE SUMMARY
┌──────────────────────────┬──────────────┐
│ Category │ Issues Found │
├──────────────────────────┼──────────────┤
│ 1. Formal Passive Voice │ 7 │
│ 2. Hidden Actors │ 6 │
│ 3. Weak "To-Be" Wind-ups │ 1 │
│ 4. Nominalizations │ 2 │
│ 5. Modal Hesitation │ 1 │
│ TOTAL IMPROVEMENTS │ 17 │
└──────────────────────────┴──────────────┘
The skill listed the issues by categories. The location pointed to the nearest heading, and the search string helped me locate the sentence in the blog post, where I fixed it. The rationale explained the error to help the ESL writer learn.
The table summarized my weak areas, enabling simultaneous learning and editing.
Update the Command to use Agent Skills
Next, I refactored the original blog-review.toml Custom Command to call these specific skills. This centralized the logic and ensured the AI used our high-precision rules.
description = "Exhaustive 9-Point Markdown Auditor: Powered by specialized high-precision editorial skills."
prompt = """
You are a Senior Technical Copyeditor and ESL Writing Coach. Your goal is to identify EVERY SINGLE error in the provided Markdown content by executing specialized editorial skills.
### EXHAUSTIVE AUDIT PROTOCOL:
1. **Multi-Pass Execution:** Scan the text 9 times—once for each focus area.
2. **Skill-Specific Logic:**
- For Area 1: Execute the **grammar-syntax-reviewer** (7-category check).
- For Area 9: Execute the **active-voice-reviewer** (Eliminate nominalizations and hesitation).
3. **No Omissions:** List every single occurrence. If an error appears 10 times, list all 10.
4. **Searchability Priority:** Provide the nearest Heading and the **Full Sentence** containing the error so the user can use Ctrl+F.
### FOCUS AREAS:
1. **[Skill: grammar-syntax-reviewer]:** Audit for (a) Subject-verb agreement with intervening phrases, (b) Tense consistency, (c) Preposition precision, (d) Pronoun clarity, (e) Comma splices, (f) Count vs. Non-count nouns (Code, Software, Data), and (g) Technical Plurals vs. Possessives.
... Other focus areas ...
9. **[Skill: active-voice-reviewer]:** Audit for (a) Formal passive voice, (b) Hidden actors, (c) "To-be" wind-ups (e.g., 'There are'), (d) Nominalizations (e.g., 'Perform an analysis' -> 'Analyze'), and (e) Modal hesitation (e.g., 'You should click' -> 'Click').
### CONSTRAINTS:
- **DO NOT** output the full polished text.
- **DO NOT** report errors found inside code blocks (<triple ticks>).
- **LOCATION:** You MUST provide:
1. The nearest **Heading** (e.g., ## Setup).
2. A **Search String**: The full sentence containing the error (for easy Ctrl+F).
### CONTENT TO AUDIT:
<content>
{{args}}
</content>
### OUTPUT FORMAT:
#### 🔬 EXHAUSTIVE LINGUISTIC AUDIT
### [Category Name]
- **Skill Applied:** [Insert Skill Name, e.g., technical-punctuation-reviewer]
- **Location:** [Nearest Heading Name]
- **Search String:** "[The full sentence where the error exists]"
- **Fixed:** "[The corrected full sentence]"
- **Rationale:** **[Formal Rule Name]**: [Brief explanation of the rule to help the writer learn.]
---
#### 📊 AUDIT SUMMARY
| Category | Issues Found |
| :--- | :--- |
| 1. Grammar & Syntax (Deep) | [Count] |
| 9. Active Voice (Instructional) | [Count] |
| **TOTAL** | **[Sum]** |
"""
{{args}} is the placeholder for the user's input file or text.
The skills are enabled in the CLI, the model perceives them as available functions or tools and maps the text instruction "Execute..." to the appropriate tool definition.
The name field in the SKILL.md frontmatter registers the skill as a tool that the model can invoke by name.
In the Gemini CLI chat, I ran the blog-review command, and the activated skills scanned the content to output the errors and summarize the count in a table.
/blog-review @test_agent_skills.md
🔬 EXHAUSTIVE LINGUISTIC AUDIT
1. Grammar & Syntax (Deep)
- Skill Applied: grammar-syntax-reviewer
- Location: ## Introduction
- Search String: "In this post, I will explore retrieving the Premier League 2025/2026 Player statistics..."
- Fixed: "In this post, I explore retrieving the Premier League 2025/2026 Player statistics..."
- Rationale: [Tense Consistency]: Use the present tense ("I explore") for the document's narrative to match "I walk through" and "describe".
... other issues ...
2. Articles & Determiners (Noun-First)
- Skill Applied: missing-article-reviewer
- Location: ## Environment Variables
- Search String: "I use the client to call Gemini 3 Flash Preview model to retrieve data..."
- Fixed: "I use the client to call the Gemini 3 Flash Preview model to retrieve data..."
- Rationale: [Missing Article]: "Model" is a singular countable noun unmodified by a determiner in the original phrase.
... other issues ...
3. Word Choice
- Skill Applied: lexical-precision-reviewer
- Location: ## Lessons Learned
- Search String: "When the player was Kaoru Mitoma, the model worked hard to find the results via Google Search..."
- Fixed: "When the player was Kaoru Mitoma, the model executed a deep search via Google Search..."
- Rationale: [Anthropomorphism]: "Worked hard" assigns human effort to software. Use precise technical terms like "executed a deep search."
... other issues ...
4. Punctuation
- Skill Applied: technical-punctuation-reviewer
- Location: ## Architecture
- Search String: "![High level architecture of Retrieving Premier League Player Stats...]"
- Fixed: "![High-level architecture of Retrieving Premier League Player Stats...]"
- Rationale: [Compound Modifier]: "High-level" modifies "architecture" and must be hyphenated.
... other issues ....
6. Parallelism
- Skill Applied: parallelism-check
- Location: ## Prerequisites
- Search String: "Python: Have Python 3.12+ and the google-genai SDK installed."
- Fixed: "Python: Python 3.12+ and the google-genai SDK."
- Rationale: [List Structure]: The other items in the list are Noun Phrases ("Vertex AI...", "A Google Cloud API Key..."). This item uses an
imperative ("Have...").
9. Active Voice (Instructional)
- Skill Applied: active-voice-reviewer
- Location: ## Introduction
- Search String: "When the URL is invalid or the data is missing... the Google Search Tool is used."
- Fixed: "When the URL is invalid or the data is missing... the model uses the Google Search tool."
- Rationale: [Formal Passive Voice]: "Is used" hides the actor (the model).
... other issues ...
The table displayed the number of issues that the skills and the rest of the Custom Command identified.
📊 AUDIT SUMMARY
┌────────────────────────────────────────┬──────────────┐
│ Category │ Issues Found │
├────────────────────────────────────────┼──────────────┤
│ 1. Grammar & Syntax (Deep) │ 6 │
│ 2. Articles & Determiners (Noun-First) │ 4 │
│ 3. Word Choice │ 2 │
│ 4. Punctuation │ 5 │
│ 5. Technical Accuracy │ 0 │
│ 6. Parallelism │ 1 │
│ 7. Expert Blindness │ 0 │
│ 8. Conciseness │ 0 │
│ 9. Active Voice (Instructional) │ 7 │
│ TOTAL │ 25 │
└────────────────────────────────────────┴──────────────┘
The test blog post had 25 issues; I used the heading and the text to search for and find issues to resolve.
I prototyped the skills locally, so I decided to package them into a distributable Extension so others can install them easily.
Packaging for Distribution: Creating a CLI Extension
To package the commands and skills for portability, I created an extension by running the gemini extensions new command.
gemini extensions new blog-post-pro-editor
The command created a new extension named blog-post-pro-editor. I copied the skills and commands folders from ~/.gemini to blog-post-pro-editor.
Structure:
├── commands
│ ├── blog-review.toml
│ └── critique.toml
├── gemini-extension.json
└── skills
├── active-voice-reviewer
│ └── SKILL.md
├── grammar-syntax-reviewer
│ └── SKILL.md
├── lexical-precision-reviewer
│ └── SKILL.md
├── missing-articles-reviewer
│ └── SKILL.md
└── technical-punctuation-reviewer
└── SKILL.md
I started each file in skills/ with YAML frontmatter:
---
name: grammar-syntax-reviewer
description: A high-precision editorial skill focused on subject-verb agreement, tense consistency, prepositional accuracy, and structural integrity in technical writing.
---
# <Skill Name>
## PERSONA
<Persona of the skill>
(The refactored prompt goes here)
I started each file in commands/ with a description and a prompt:
description = "<Description of the blog review command>"
prompt = """
<Prompt of the blog review command and the skill instructions>
""""
Install the Extension and Run Locally
During development, I installed the skills and commands to test the Gemini CLI extension locally.
cd blog-post-pro-editor
gemini extension link .
The CLI linked and enabled the 'blog-post-pro-editor' extension in the terminal.
Extension "blog-post-pro-editor" linked successfully and enabled.
Next, I started gemini and typed the following to activate the skills and find grammar issues in the Markdown file.
> Find the grammar errors in @test_agent_skills.md
The CLI activated the grammar-syntax-reviewer and missing-articles-reviewer skills to identify structural and article-related errors in my blog post.
The skills output the following results in a table. The Grammar & Syntax skill found 3 errors, and the Missing Articles skill found 7 errors.
┌──────────────────────────────┬──────────────┐
│ Category │ Issues Found │
├──────────────────────────────┼──────────────┤
│ Grammar & Syntax │ │
│ 2. Tense Consistency │ 1 │
│ 3. Preposition Precision │ 1 │
│ 5. Fragments/Run-ons/Splices │ 1 │
│ Articles & Determiners │ │
│ 1. Missing Articles │ 7 │
│ TOTAL ERRORS │ 10 │
└──────────────────────────────┴──────────────┘
I packaged the skills and the commands into an extension to install them on any machine with the Gemini CLI.
I verified the new extension in the ~/.gemini/extensions folder. The command showed blog-post-pro-editor in the extension list.
ls ~/.gemini/extensions
Conclusion
By breaking the blog-review Custom Command into Agent Skills and packaging them into an Extension, we have built a comprehensive editorial suite. Execute individual skills in a Gemini CLI chat to locate relevant linguistic errors in a blog post using natural language. Similarly, enter the Custom Command blog-review in the same chat to scan the blog post and identify all linguistic errors explicitly. This modular approach ensures higher accuracy for ESL writers and makes your AI tools portable across any machine.
Top comments (0)