Agents and Skills¶

CMS Cultivator features a two-tier architecture:

1. Specialist Agents - Orchestrate complex workflows (spawned by skills)
2. Agent Skills - Knowledge base (auto-invoked by context, or explicitly invoked)

Specialist Agents¶

Agents are specialized AI assistants that handle complex, multi-step workflows. When you run a command, it spawns the appropriate agent to coordinate the work.

Agent Architecture¶

Leaf Specialists (work independently):

• documentation-specialist - API docs, guides, and changelogs
• responsive-styling-specialist - Mobile-first SCSS generation with WCAG AA contrast
• browser-validator-specialist - Real-browser validation via Chrome DevTools MCP
• drupalorg-issue-specialist - drupal.org issue drafting and formatting
• drupalorg-mr-specialist - Merge request setup on git.drupalcode.org
• pr-review-specialist - Fresh-context code review for pr-review self, read-only

Orchestrators (coordinate complex workflows):

• testing-specialist - Test generation and coverage (inline security and accessibility test scenarios)
• design-specialist - Design-to-code generation (code generation only; skill spawns responsive-styling and browser-validator agents)

PR and development-workflow skills (pr-create, pr-review, pr-release, commit-message-generator, worktree-manager) run directly from the main session without an orchestrator agent — each skill contains its complete workflow. The one exception: pr-review self spawns pr-review-specialist so the review runs in a fresh context.

How Agents Work¶

"I need to commit my changes"
    ↓
Main session runs commit-message-generator skill directly
    ↓
    ├─→ Analyzes staged changes (git status, git diff)
    ├─→ Generates conventional commit message
    ↓
Presents for user approval → runs git commit

"create a PR"
    ↓
Main session runs pr-create skill directly
    ↓
    ├─→ Analyzes git changes
    ├─→ Reviews test coverage inline (Read/Glob)
    ├─→ Checks security concerns inline (Grep patterns)
    ├─→ Checks accessibility concerns inline (Grep on UI files)
    ├─→ Detects Drupal/WordPress deployment requirements
    ↓
Presents full PR description for user approval → runs gh pr create

Agent Orchestration Patterns¶

Inline Quality Checks (Skill-Level)¶

The pr-create and pr-review skills perform quality checks inline directly from the main session — no agent in between:

PR with UI changes:
  → Reviews accessibility concerns inline using Read/Grep

PR with authentication code:
  → Reviews security concerns inline using Read/Grep

PR with new features:
  → Reviews test coverage inline using Read/Glob

Sequential Skill-Level Spawning¶

The design-to-wp-block and design-to-drupal-paragraph skills orchestrate sequential agent calls:

/design-to-wp-block [figma-url]
    ↓
Spawns design-specialist (code generation)
    ↓
Spawns responsive-styling-specialist (SCSS from design-specialist output)
    ↓
Spawns browser-validator-specialist (validation from test URL)

Agent-to-Skill Mapping (Spawned By)¶

PR skills (pr-create, pr-review, pr-release, commit-message-generator) run directly from the main session — no agent is spawned, except pr-review self, which spawns pr-review-specialist.

Agent-to-Skill Mapping¶

Each agent uses specific skills for detailed "how-to" knowledge:

PR skills (pr-create, pr-review, pr-release, commit-message-generator, worktree-manager) run directly from the main session — they use the relevant tooling (GitHub CLI, git) without an orchestrator agent. pr-review self is the exception: it spawns pr-review-specialist for a fresh-context review.

Why Agents?¶

Benefits for Users: - 🚀 Parallel Execution - Multiple specialists work simultaneously (e.g., design-to-code pipelines) - 🎯 Comprehensive Checks - Orchestrators ensure nothing is missed - 📊 Unified Reporting - Clear, consolidated findings from multiple specialists - 🔄 Consistent Quality - Each specialist follows best practices

Benefits for Development: - 🧩 Modular Design - Each agent has one clear responsibility - 🔧 Composable - Agents can be combined in new ways - ✅ Maintainable - Clean separation of concerns - 🔍 Testable - Each agent can be tested independently

Agent Skills¶

Agent Skills are model-invoked capabilities—Claude decides when to use them based on your conversation context, without you needing to remember specific command names.

Two-Tier System Explained¶

Available Skills¶

1. commit-message-generator¶

Automatically triggers when you: - Say "I need to commit" or "ready to commit" - Mention "staged changes" or "git commit" - Ask "what should my commit message be?"

What it does: - Analyzes git diff --staged - Generates one conventional commit message and presents it for approval - Follows the repository's existing commit style - Includes proper scope and description - Appends an Assisted-by: trailer when AI assisted the change itself

Example:

You: "I fixed the login bug, ready to commit"
Claude: "I'll generate a commit message for your login fix..."

Generated:
fix(auth): resolve session timeout on remember-me login

- Correct cookie expiration logic
- Add test coverage for remember-me flow

Would you like me to commit with this message?

Explicit invocation: /commit-message-generator - For explicit commit message generation

2. code-standards-checker¶

Automatically triggers when you: - Ask "does this follow standards?" - Ask what to run after editing PHP, Twig, JS, or SCSS - Mention "coding standards", "linting", "PHPCS", "PHPStan", "Rector", or "ESLint" - Ask "should I fix the style?"

What it does: - Reads the scripts blocks in composer.json and package.json to find the project's own commands, at the level that owns the changed files - Prefixes with ddev when .ddev/ is present - Runs auto-fix before check-only (phpcbf then phpcs, format then lint:js) and verifies afterward - Falls back to raw tool invocations when no script alias exists - Reports remaining violations with file:line and the re-verify command

Example:

You: "I just edited the SCSS in the theme — what do I need to run?"
Claude: "The theme's package.json defines lint:css and build.

ddev npm run lint:css   # wp-scripts lint-style
ddev npm run build      # compile the production assets

Running both now..."

Explicit invocation: /code-standards-checker - For comprehensive project-wide standards checks

3. test-scaffolding¶

Automatically triggers when you: - Show code and say "I need tests" - Ask "how do I test this?" - Mention "no tests yet" or "untested code" - Say "should write unit tests"

What it does: - Analyzes the code to test - Generates appropriate test scaffolding - Creates PHPUnit/Jest/Cypress tests - Includes test cases for happy path and errors

Example:

You: "I just wrote this UserManager class, need tests"
Claude: "I'll generate PHPUnit tests for UserManager.

I see 3 methods: createUser(), getUser(), deleteUser().
I'll create tests for:
- Valid input (happy path)
- Invalid input (error cases)
- Edge cases (null, empty values)

[Generates test file with complete structure]"

Explicit invocation: /test-scaffolding - For batch test generation across modules

4. documentation-generator¶

Automatically triggers when you: - Say "I need to document this" - Ask "how do I write API docs?" - Mention "README", "docblock", or "API documentation" - Show code and ask "what docs do I need?"

What it does: - Generates API documentation (docblocks) - Creates README files - Writes user guides - Produces changelog entries

Example:

You: "Need to document this API endpoint"
Claude: "I'll generate API documentation for your endpoint.

[Generates complete docblock with:
- Description
- @param tags with types
- @return documentation
- @throws for exceptions
- Usage example]"

Explicit invocation: /documentation-generator - For comprehensive documentation projects

5. test-plan-generator¶

Automatically triggers when you: - Ask "what should QA test?" - Say "need a test plan" - Mention "test scenarios" or "test cases" - Show a feature and ask "how to test this?"

What it does: - Analyzes features and changes - Creates structured test scenarios - Identifies test cases (happy path, errors, edge cases) - Produces QA-ready test plans

Example:

You: "What should QA test for this login feature?"
Claude: "I'll create a test plan for the login feature.

Test Scenarios:
1. Successful login (valid credentials)
2. Failed login (invalid password)
3. Account lockout (3 failed attempts)
4. Remember me functionality
5. Password reset flow

[Generates complete test plan with steps and expected results]"

Explicit invocation: /test-plan-generator - For comprehensive QA documentation

6. coverage-analyzer¶

Automatically triggers when you: - Ask "what's not tested?" - Mention "test coverage" or "coverage report" - Say "which code is untested?" - Show code and ask "is this tested?"

What it does: - Analyzes PHPUnit/Jest coverage - Identifies untested code paths - Suggests missing test cases - Prioritizes critical untested code

Example:

You: "What code doesn't have tests?"
Claude: "Analyzing test coverage...

Overall: 72%

🔴 Critical gaps (0% coverage):
- PaymentProcessor.php (handles money!)
- AuthService.php (security-sensitive)

🟡 Partial coverage:
- UserManager.php (45%)
  ✅ Tested: getUser(), createUser()
  ❌ Missing: deleteUser(), updatePermissions()

Recommendation: Add tests for payment/auth first."

Explicit invocation: /coverage-analyzer - For comprehensive coverage analysis with trends

7. drupal-sdc-twig¶

Automatically triggers when you: - Mention "SDC", "Single Directory Component", or "component.yml" - Work with components/ folders in a Drupal theme or module - Write or review an SDC Twig template - Ask "props or slots?", "embed vs include?", or "how should I structure this Drupal component?"

What it does: - Guides props vs slots decisions (the most common SDC refactor source) - Explains .twig extension (not .html.twig) and schema requirements - Shows correct attributes object usage on root elements - Demonstrates include() vs embed patterns for composition - Covers escaping rules (never pass raw HTML through props) - Provides accessibility checklist for component development - Explains libraryOverrides, component replacement, and variants (Drupal 11.2+)

Example:

You: "Should this heading be a prop or a slot?"
Claude: "Use the props vs slots decision tree:

1. Will the template's HTML structure change based on this value?
   → Yes (heading_level affects <h2> vs <h3>) → prop
2. Will you render it 1:1 inside a container? → slot
3. Could it be a render array or nested component someday? → slot

For headings: expose heading_level as a prop (enum 2-6) and
heading_text as a slot. This lets consumers control the
document outline while passing any markup for the text."

Explicit invocation: None — this skill activates conversationally for Drupal SDC questions

How to Use Agent Skills¶

Natural Conversation¶

Simply talk to Claude naturally—the skills activate automatically:

✅ "I need to commit my changes"
✅ "How do I test this function?"
✅ "Does this follow Drupal standards?"
✅ "Should this heading be a prop or a slot?"
✅ "Need to document this API endpoint"

No need to remember command names or syntax!

When to Invoke Skills Explicitly¶

Use explicit skill invocation when you want:

Structured workflows: - pr-create / @pr-create - Create PR with full description - pr-review 123 / @pr-review 123 - Review specific PR - pr-release / @pr-release - Generate changelog and deployment notes

Batch operations: - test-scaffolding / @test-scaffolding - Generate tests for entire module - documentation-generator api / @documentation-generator api - Generate all API documentation

Skill Activation Tips¶

Be Specific About Context¶

Less effective:

"Check this code"

More effective:

"Does this follow standards?" → Triggers code-standards-checker
"I need tests for this class" → Triggers test-scaffolding
"What's not covered by tests?" → Triggers coverage-analyzer

Show Relevant Code¶

Skills work best when you show the code you're asking about:

"Here's my UserManager class:
[paste code]

I need tests for this."

→ Triggers test-scaffolding skill

Use Natural Language¶

Don't try to "game" the system—just describe what you need:

✅ "I fixed the bug and I'm ready to commit"
❌ "Use commit-message-generator skill"

Skills Reference Table¶

Integration with Workflow¶

Agent Skills complement your development workflow:

During Development¶

• coding → code-standards-checker validates style
• wrote function → documentation-generator adds docblocks
• need tests → test-scaffolding generates tests

Before Committing¶

• staged changes → commit-message-generator creates message
• is code tested? → coverage-analyzer checks gaps

Before PR¶

• self-review → pr-review analyzes your branch
• browser check → browser-validator tests responsive behavior and accessibility
• standards check → code-standards-checker validates style

During Code Review¶

• All skills available for reviewers to validate code

Disabling Skills (If Needed)¶

Agent Skills are project-level by default. To disable:

For current session:

# Skills are in .claude/skills/ for team collaboration
# Or ~/.claude/skills/ for personal use

To prevent auto-activation: Simply invoke the skill explicitly—Claude will respect your explicit choice.

Learning More¶

• General Skills Documentation: Claude Code Skills
• Codex Plugin Documentation: OpenAI Codex Plugins
• Creating Custom Skills: See Contributing guide
• Skills Reference: See Skills Overview

Key Takeaway: Agent Skills make CMS Cultivator proactive—Claude helps automatically when it sees you need assistance, while explicit invocation gives you direct control over comprehensive workflows.