Skip to content

Skill Conventions

Jump to bottom
Paulo Maia Carvalho edited this page May 20, 2026 · 1 revision

Skill Conventions

Conventions that all DrupalClaw skills follow. Stick to these when writing new skills so behaviour is consistent and the agent can reason predictably.

Naming

  • Folder and name frontmatter must match exactly.
  • Use kebab-case: drupal-my-skill, not drupal_my_skill or drupalMySkill.
  • Drupal-specific skills are prefixed drupal-. Generic workspace skills have no prefix.

Project root

All Drupal skills assume the project root is /workspace/drupal. Never use /workspace as the Drupal root — the top-level workspace directory contains config and tooling that are not the Drupal project.

DRUPAL_DIR="/workspace/drupal"
cd "$DRUPAL_DIR" || { echo "❌ /workspace/drupal not found. Run /drupal-init first."; exit 1; }

Docker awareness

Every skill that runs Drush or PHP must detect whether the stack is running and route accordingly:

  1. Check for a running PHP-FPM container matching drupal.*(php|fpm).
  2. If found → use docker exec.
  3. If not found → fall back to local vendor/bin/drush (for local dev without Docker).
  4. If neither → fail with a clear message pointing to /drupal-serve.

Never hardcode the container name — it varies by project and compose configuration.

Output conventions

Signal Prefix
Success / step complete ✓
Info / neutral (plain text)
Warning ⚠
Error / stop ❌
Docker context detected 🐳 Stack active: <container>

Emit one status line per major action so the user can follow progress. Don't flood with verbose output — summarise when possible.

Exit codes

  • exit 1 on any unrecoverable error.
  • Do not suppress errors with 2>/dev/null unless the failure is expected and handled.

User prompts

When user input is required mid-skill:

  • Ask a single, focused question.
  • Offer a default in brackets: Press Enter for [mariadb].
  • Never ask for information that can be detected from the environment.

Parameter handling

PARAM="${1:-}"
if [[ -z "$PARAM" ]]; then
  echo "❌ Missing parameter. Usage: /skill-name <value>"
  exit 1
fi

Extract from $1, $2, etc. Don't parse complex argument strings — keep skill invocations simple.

Drush working directory

Always pass -w /var/www/html to docker exec so Drush finds the project root inside the container:

docker exec -i -w /var/www/html "$PHP_CONTAINER" vendor/bin/drush <command>

Gzip support

Skills that handle SQL dumps must support .sql.gz files:

if [[ "$DUMP_FILE" == *.gz ]]; then
  gunzip -c "$DUMP_FILE" | $DRUSH sqlq --file=/dev/stdin
else
  $DRUSH sqlq --file="$DUMP_FILE"
fi

Skill descriptions

Keep descriptions under 80 characters. They appear in the UI skills panel and must be scannable at a glance. Focus on what the skill does, not how.

Good: Install a contrib module via Composer and enable it Bad: This skill uses Composer to install a contrib module and then runs drush en to enable it in the current Drupal installation

Testing checklist

Before shipping a new skill:

  • Works when stack is running (Docker path)
  • Works or fails gracefully when stack is not running
  • Works or fails gracefully when /workspace/drupal doesn't exist
  • Missing parameters produce a helpful error, not a bash traceback
  • Output is readable in the chat panel (no ANSI escape codes unless explicitly needed)

Clone this wiki locally