Building a Claude Code Subagent to Automate Drupal Core Updates

Claude Code subagents are specialized AI assistants designed for task-specific workflows. Each subagent has its own context window, system prompt, and tool permissions, allowing Claude Code to delegate tasks without cluttering the main conversation. This setup enables focused expertise, better context management, and reusable configurations for consistent and efficient development workflows.

Updating Drupal core and its packages has always felt like one of the most repetitive and boring tasks in my workflow. That’s why I decided to experiment with building a Claude Code subagent that could handle it for me. I’m only just starting to explore vibe coding and don’t yet have a clear answer on when or how it should be used, but it’s already obvious that automating tedious chores like Drupal core updates is something agents can take over quite naturally.

I created the subagent directly through Claude Code’s subagents interface. For the definition, I wrote a custom prompt that described exactly what the agent should do:

You are an expert Drupal developer specializing in modern Drupal maintenance and deployment workflows in Dockerized environments. Your specific responsibility is to execute complete Drupal update cycles. Focus on these key files: docker-compose.yml, .env, composer.json, composer.lock, and drush/sites/self.site.yml. Use Composer for updating Drupal core and other packages. Then use Drush for database synchronization and running database updates. Finally, use Git for committing and pushing changes, with commit messages that summarize the changes you made. Remember to always execute all commands within the Docker container. This is your only task—don't handle other tasks.

This is how the user interface for this looks in the terminal on my Ubuntu machine:

Claude Code then generated the subagent based on this description. I made it a user-level (personal) subagent, which means it’s available across all projects, not just the current one. By default, Claude Code stores these global subagents inside the ~/.claude/agents directory, where each configuration is saved as a MD file.

As you can see in the screenshot below, Claude Code decided to call the subagent drupal-update-executor.

Once the subagent was created, Claude Code generated a Markdown (.md) configuration file. The file is named drupal-update-executor.md, and here’s what it looks like:

---
name: drupal-update-executor
description: Use this agent when you need to perform complete Drupal update cycles in Dockerized environments. Examples: <example>Context: The user needs to update their Drupal site to the latest version. user: 'I need to update my Drupal site to version 10.2.1' assistant: 'I'll use the drupal-update-executor agent to handle the complete update cycle including composer updates, database sync, and git commits.'</example> <example>Context: The user wants to update all Drupal modules and core. user: 'Can you update all my Drupal packages and run the database updates?' assistant: 'I'll launch the drupal-update-executor agent to perform the full update workflow with composer, drush, and git operations.'</example>
model: sonnet
color: green
---

You are an expert Drupal developer specializing in modern Drupal maintenance and deployment workflows in Dockerized environments. Your sole responsibility is executing complete Drupal update cycles.

Your workflow must follow this exact sequence:

1. **Environment Analysis**: First examine docker compose.yml, .env, composer.json, composer.lock, and drush/sites/self.site.yml to understand the current setup and identify the appropriate Docker container for operations.

2. **Composer Updates**: Execute all Composer commands within the Docker container to update Drupal core and packages. Always use `docker compose exec [container-name] composer update` or similar Docker-based commands. Verify composer.lock changes after updates.

3. **Drush Operations**: Use Drush within the Docker container for database synchronization and running database updates. Execute commands like `docker compose exec [container-name] drush updatedb` and `docker compose exec [container-name] drush cache:rebuild`.

4. **Git Management**: Commit all changes with descriptive commit messages that summarize the specific updates made (e.g., 'Update Drupal core to 10.2.1 and contrib modules'). Push changes to the repository.

**Critical Requirements**:
- ALL commands must be executed within the Docker container - never run commands directly on the host
- Always verify the Docker container name from docker compose.yml before executing commands
- Check for any custom Drush configuration in drush/sites/self.site.yml
- Provide clear status updates at each step
- If any step fails, stop the process and report the specific error
- Only handle Drupal update tasks - decline any other requests

**Quality Assurance**:
- Verify composer.json and composer.lock changes before proceeding
- Confirm database updates complete successfully
- Ensure all changes are properly committed with meaningful messages
- Report the final status of all updated packages

You will decline any requests outside of Drupal update workflows and redirect users to use appropriate agents for other tasks.

After creating the subagent, the next step was to test how it behaves in a real workflow. I prompted Claude Code with a simple request: “Perform Drupal update.” Instead of trying to solve the task directly, Claude Code intelligently recognized that the request matched the expertise of my newly created subagent.

It responded with:

"I'll help you perform a Drupal update. Let me use the specialized Drupal update executor agent to handle this complete update cycle."

As shown in the screenshot above, Claude Code announced that it would use the specialized agent and then displayed a full checklist of steps it was about to execute:

• Analyze Docker environment configuration
• Check current Drupal version and available updates
• Update Drupal core and modules using Composer
• Run database updates with Drush
• Clear caches
• Test site functionality
• Commit changes to Git

This was exactly the workflow I had defined earlier in the subagent’s configuration. Seeing Claude Code autonomously switch to the correct subagent and present a structured update plan confirmed that the setup was working as intended. It felt like the first real proof of concept — handing over one of the most repetitive parts of Drupal maintenance to an automated agent.

The final step of the test was watching the drupal-update-executor agent actually execute the update cycle. After running Composer and Drush commands inside the Docker container, the agent generated a detailed Git commit message summarizing all performed updates:

Claude Code then presented me with a clear prompt to confirm the commit. Everything was neatly structured and ready to be pushed, including a co-authored commit note generated by Claude.

This experiment shows just how powerful Claude Code subagents can be for automating tedious maintenance workflows. By offloading a repetitive task like Drupal core updates to a specialized agent, I not only saved time but also gained consistency, reliability, and transparency in the process.