Claude Skill

contribution-setup

Stands up and environment-matches a Drupal contribution workspace — DDEV with the workflow-matched add-on, CI gate config (new-module scaffold or existing-module discovery), the Drupal AI skills, the drupalorg CLI, the GitLab CLI (glab) for authenticated git.drupalcode.org operat

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download camoa-claude-skills-drupal-ai-contrib_skills_contribution-setup-c73ba2a.zip · 4 KB

Install

skills CLI npx skills add https://github.com/camoa/claude-skills/tree/main/drupal-ai-contrib/skills/contribution-setup
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install camoa-claude-skills@llmmart
Git git clone https://github.com/camoa/claude-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole camoa/claude-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Contribution Setup (worker skill)

Onboarding for a Drupal contribution. Optional, idempotent, not a gate. Detect what already exists and do only what is missing — a contributor who arrives with a ready environment can skip straight to issue.

Backs /drupal-ai-contrib:setup. Load the knowledge layer via dev-guides-navigator: drupal/contributing/ddev-contribution-environment, drupal/contributing/contrib-project-scaffolding, drupal/contributing/three-contribution-workflows-compared, drupal/contributing-with-ai/ai-toolchain-for-contribution.

Procedure

1. Detect the workflow and issue system

Determine — by inspecting the working directory and asking the contributor only what cannot be inferred:

  • Workflow — core / your own contrib / someone else's contrib (the three workflows differ in authority, CI ownership, who merges). See the workflows dev-guide.
  • Issue system — drupal.org classic queue vs. GitLab. Detect by following the project's Issues link; do not assume.

2. Detect the environment

Check for an existing DDEV project (.ddev/config.yaml) and the add-on in use. If a working contribution environment already exists, report it and stop — nothing to do.

If none exists, stand up DDEV with the workflow-matched add-on:

Workflow Add-on
Single contrib module/theme ddev-drupal-contrib (module repo is the project root; web/ + vendor/ generated & gitignored)
Multi-module suite ddev-drupal-suite
Drupal core ddev-drupal-core-dev

3. Resolve the gate config — two modes

Existing module — discover gates by parsing .gitlab-ci.yml:

  • Read the gitlab_templates include and ref, the variables: block (_TARGET_CORE, _TARGET_PHP, _GITLAB_TEMPLATES_REF, _PHPUNIT_CONCURRENT, SKIP_*, OPT_IN_TEST_*).
  • Record the discovered gate set; verify will mirror exactly these.

New module / maintainer setup — scaffold the correct config (writes — see §Writes). Generate, version-resolved per the target core, from the scaffolding dev-guide:

  • .gitlab-ci.yml — the gitlab_templates include + a variables: block
  • phpcs.xml.dist — Drupal + DrupalPractice, scoped to src + tests
  • phpstan.neon — phpstan-drupal extension, the project's level
  • phpunit.xml.dist — the major-version-correct schema (D11 → PHPUnit 11 schema, <source> block, failOnWarning; D10 → PHPUnit 9.x schema + DrupalListener) — copy from the target core, never hand-write the version
  • .cspell-project-words.txt
  • drupal/core-dev (+ drupal/coder, phpstan/phpstan, mglaman/phpstan-drupal) in require-dev, constrained to the target major

4. Ensure the toolchain

Drupal AI skills — ensure ai_best_practices and ai_skills are installed via drupal_devkit (the cross-harness skill installer). If drupal_devkit is absent, report how to obtain it; do not block.

The issue / MR CLI — the issue, submit, and pipeline skills wrap mglaman/drupalorg-cli. Detect it with command -v drupalorg (the executable is drupalorg, not drupalorg-cli). If it is missing, surface the install instructions from ${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md — that reference covers what the tool is, the recommended PHAR install, the deprecated Composer path, and the subcommand set. Offer to install it; do not block if the contributor declines (issue/submit re-surface the same instructions).

The GitLab CLI (glab) — authenticated GitLab writes on migrated projects (fork push, MR create/update, pipeline status) are delegated to the drupal-gitlab skill, which drives glab against git.drupalcode.org. The drupal-gitlab skill itself ships with ai_best_practices (installed above via drupal_devkit) — no install step for the skill — but glab is a separate binary. Detect and report it:

command -v glab                                  # installed?
glab auth status --hostname git.drupalcode.org   # authenticated for Drupal's GitLab?

If glab is missing or not authenticated, surface the next step — install glab, then glab auth login --hostname git.drupalcode.org (a write-capable token is needed only for pushes / MR creation; reads work read-only — see the drupal-gitlab README for token scopes). Soft posture, exactly like the drupalorg check: report the gap, never block. The legacy drupalorg reads still work without glab; only migrated-project authenticated writes need it.

5. Check contribution credentials — and guide, do not assume

The contribution arc needs the contributor's drupal.org credentials for its write operations. Surface this now — do not let it surface mid-issue as a failed git push. The plugin and the CLI cannot set credentials up; this is the contributor's own account action. Guide them through it.

  • Read operations (drupalorg issue:show, mr:list, project:issues) hit public APIs — no credentials needed. An empty project:issues result can itself be an auth/config gap rather than "no issues" — note that when reporting.
  • Write / push operations — git push to an issue fork, and the /do: issue-bot commands — need an SSH key registered on the contributor's drupal.org account, because issue-fork git remotes use SSH URLs (git@git.drupal.org:…).

Detect, then guide:

ssh -T git@git.drupal.org      # a working key greets the contributor by username

If it does not authenticate, tell the contributor plainly: this is a ~2-minute action — register an SSH key at drupal.org → My account → SSH keys (add the public key, e.g. ~/.ssh/id_ed25519.pub). It is the prerequisite for git push to issue forks; without it, issue can still review and read, but cannot push a branch. Never block setup on it — report it as the next thing to do. See ${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md §Authentication.

6. Environment-match

Install the CI-target core version + drupal/core-dev so phpunit / phpstan resolve to the same releases CI uses (the local DDEV default usually will not match). This is the mechanism that makes verify's gates trustworthy — see contribution-verify.

7. Report

Summarize, and for each item state ready vs. needs-action so the contributor knows their exact next step: workflow, issue system, environment status, the resolved gate set, AI-skill status, the issue/MR CLI (drupalorg) status, the GitLab CLI (glab) status (installed + authenticated for git.drupalcode.org), the credentials/SSH-key status, the environment-match result. Point the contributor at issue (or, if work is underway, verify) — and if the SSH key is missing, name that as the first step.

Writes — explicit confirmation only

setup writes files only with explicit user confirmation and only within the target project. Show the contributor each file to be written before writing it. Never write outside the project directory.

Detect-driven

Every step checks first and does only what is missing. Re-running setup on a ready environment is a no-op that simply reports state.

Examples

Example 1: existing module, environment ready

Trigger: /drupal-ai-contrib:setup in a contrib module that already has DDEV. Actions:

  1. Detect the workflow (someone else's contrib) and the GitLab issue system.
  2. DDEV already present → report it, do not re-create.
  3. Parse .gitlab-ci.yml, record the discovered gate set; environment-match the core. Result: No files written; the contributor is told to proceed to issue.

Example 2: new module, maintainer setup

Trigger: /drupal-ai-contrib:setup in a fresh contrib module with no CI config. Actions:

  1. Stand up DDEV with ddev-drupal-contrib.
  2. Show each scaffold file (.gitlab-ci.yml, phpcs.xml.dist, phpstan.neon, phpunit.xml.dist, .cspell-project-words.txt) and write only on confirmation. Result: A CI-ready module the maintainer owns.

Troubleshooting

Situation Handling
drupal_devkit not installed Report how to obtain it; do not block setup.
drupalorg not on PATH Surface references/drupalorg-cli.md (PHAR install); offer to install; do not block. If installed via Composer global, the bin dir may just be off PATH — see the reference's Install note.
glab missing or not authenticated Report it as a next step (install glab; glab auth login --hostname git.drupalcode.org); never block. Only migrated-project authenticated writes need it — drupalorg reads and the legacy queue work without it. See references/drupalorg-cli.md §Hybrid model.
No SSH key registered on the drupal.org account Guide the contributor to add one (drupal.org → My account → SSH keys); report it as the next step. Read/review still works; git push to issue forks does not. Never block.
Workflow cannot be inferred Ask the contributor — never assume core vs. contrib.
.gitlab-ci.yml exists but uses a non-gitlab_templates setup Record what is there; verify mirrors the discovered jobs as-is.
Contributor declines a scaffold write Skip that file; report which gates remain unconfigured.
Files (claude-skills)
  • SKILL.md 9.8 KB
    ---
    name: contribution-setup
    description: "Stands up and environment-matches a Drupal contribution workspace — DDEV with the workflow-matched add-on, CI gate config (new-module scaffold or existing-module discovery), the Drupal AI skills, the drupalorg CLI, the GitLab CLI (glab) for authenticated git.drupalcode.org operations, and a contribution-credentials (SSH-key) check. Use when the user runs /drupal-ai-contrib:setup or asks to set up a Drupal contribution environment. Idempotent and detect-driven — does only what is missing; never a gate, never a prerequisite."
    version: 0.1.1
    model: inherit
    user-invocable: false
    ---
    
    # Contribution Setup (worker skill)
    
    Onboarding for a Drupal contribution. **Optional, idempotent, not a gate.** Detect what
    already exists and do only what is missing — a contributor who arrives with a ready
    environment can skip straight to `issue`.
    
    Backs `/drupal-ai-contrib:setup`. Load the knowledge layer via `dev-guides-navigator`:
    `drupal/contributing/ddev-contribution-environment`,
    `drupal/contributing/contrib-project-scaffolding`,
    `drupal/contributing/three-contribution-workflows-compared`,
    `drupal/contributing-with-ai/ai-toolchain-for-contribution`.
    
    ## Procedure
    
    ### 1. Detect the workflow and issue system
    
    Determine — by inspecting the working directory and asking the contributor only what
    cannot be inferred:
    
    - **Workflow** — core / your own contrib / someone else's contrib (the three workflows
      differ in authority, CI ownership, who merges). See the workflows dev-guide.
    - **Issue system** — drupal.org classic queue vs. GitLab. Detect by following the
      project's Issues link; do not assume.
    
    ### 2. Detect the environment
    
    Check for an existing DDEV project (`.ddev/config.yaml`) and the add-on in use.
    If a working contribution environment already exists, report it and stop — nothing to do.
    
    If none exists, stand up **DDEV** with the **workflow-matched add-on**:
    
    | Workflow | Add-on |
    |----------|--------|
    | Single contrib module/theme | `ddev-drupal-contrib` (module repo *is* the project root; `web/` + `vendor/` generated & gitignored) |
    | Multi-module suite | `ddev-drupal-suite` |
    | Drupal core | `ddev-drupal-core-dev` |
    
    ### 3. Resolve the gate config — two modes
    
    **Existing module** — discover gates by parsing `.gitlab-ci.yml`:
    - Read the `gitlab_templates` `include` and `ref`, the `variables:` block
      (`_TARGET_CORE`, `_TARGET_PHP`, `_GITLAB_TEMPLATES_REF`, `_PHPUNIT_CONCURRENT`,
      `SKIP_*`, `OPT_IN_TEST_*`).
    - Record the discovered gate set; `verify` will mirror exactly these.
    
    **New module / maintainer setup** — scaffold the correct config (writes — see §Writes).
    Generate, version-resolved per the target core, from the scaffolding dev-guide:
    - `.gitlab-ci.yml` — the `gitlab_templates` include + a `variables:` block
    - `phpcs.xml.dist` — `Drupal` + `DrupalPractice`, scoped to `src` + `tests`
    - `phpstan.neon` — `phpstan-drupal` extension, the project's level
    - `phpunit.xml.dist` — the **major-version-correct schema** (D11 → PHPUnit 11 schema,
      `<source>` block, `failOnWarning`; D10 → PHPUnit 9.x schema + `DrupalListener`) —
      copy from the target core, never hand-write the version
    - `.cspell-project-words.txt`
    - `drupal/core-dev` (+ `drupal/coder`, `phpstan/phpstan`, `mglaman/phpstan-drupal`) in
      `require-dev`, constrained to the target major
    
    ### 4. Ensure the toolchain
    
    **Drupal AI skills** — ensure `ai_best_practices` and `ai_skills` are installed via
    `drupal_devkit` (the cross-harness skill installer). If `drupal_devkit` is absent,
    report how to obtain it; do not block.
    
    **The issue / MR CLI** — the `issue`, `submit`, and `pipeline` skills wrap
    `mglaman/drupalorg-cli`. Detect it with `command -v drupalorg` (the executable is
    `drupalorg`, not `drupalorg-cli`). If it is missing, surface the install instructions
    from `${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md` —
    that reference covers what the tool is, the recommended PHAR install, the deprecated
    Composer path, and the subcommand set. Offer to install it; do not block if the
    contributor declines (`issue`/`submit` re-surface the same instructions).
    
    **The GitLab CLI (`glab`)** — authenticated GitLab writes on migrated projects (fork
    push, MR create/update, pipeline status) are delegated to the `drupal-gitlab` skill,
    which drives `glab` against `git.drupalcode.org`. The `drupal-gitlab` skill itself ships
    with `ai_best_practices` (installed above via `drupal_devkit`) — no install step for the
    skill — but `glab` is a separate binary. Detect and report it:
    
    ```bash
    command -v glab                                  # installed?
    glab auth status --hostname git.drupalcode.org   # authenticated for Drupal's GitLab?
    ```
    
    If `glab` is missing or not authenticated, surface the next step — install `glab`, then
    `glab auth login --hostname git.drupalcode.org` (a write-capable token is needed only for
    pushes / MR creation; reads work read-only — see the `drupal-gitlab` README for token
    scopes). Soft posture, exactly like the `drupalorg` check: report the gap, never block.
    The legacy `drupalorg` reads still work without `glab`; only migrated-project
    authenticated writes need it.
    
    ### 5. Check contribution credentials — and guide, do not assume
    
    The contribution arc needs the contributor's **drupal.org credentials** for its write
    operations. Surface this now — do not let it surface mid-`issue` as a failed `git
    push`. The plugin and the CLI **cannot** set credentials up; this is the contributor's
    own account action. Guide them through it.
    
    - **Read operations** (`drupalorg issue:show`, `mr:list`, `project:issues`) hit public
      APIs — no credentials needed. An empty `project:issues` result can itself be an
      auth/config gap rather than "no issues" — note that when reporting.
    - **Write / push operations** — `git push` to an issue fork, and the `/do:` issue-bot
      commands — need an **SSH key registered on the contributor's drupal.org account**,
      because issue-fork git remotes use SSH URLs (`git@git.drupal.org:…`).
    
    Detect, then guide:
    
    ```bash
    ssh -T git@git.drupal.org      # a working key greets the contributor by username
    ```
    
    If it does not authenticate, tell the contributor plainly: this is a ~2-minute action —
    register an SSH key at *drupal.org → My account → SSH keys* (add the public key, e.g.
    `~/.ssh/id_ed25519.pub`). It is the prerequisite for `git push` to issue forks; without
    it, `issue` can still review and read, but cannot push a branch. Never block setup on
    it — report it as the next thing to do. See
    `${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md` §Authentication.
    
    ### 6. Environment-match
    
    Install the **CI-target core version** + `drupal/core-dev` so `phpunit` / `phpstan`
    resolve to the same releases CI uses (the local DDEV default usually will not match).
    This is the mechanism that makes `verify`'s gates trustworthy — see `contribution-verify`.
    
    ### 7. Report
    
    Summarize, and for each item state ready vs. needs-action so the contributor knows
    their exact next step: workflow, issue system, environment status, the resolved gate
    set, AI-skill status, the issue/MR CLI (`drupalorg`) status, the **GitLab CLI (`glab`)**
    status (installed + authenticated for `git.drupalcode.org`), the **credentials/SSH-key**
    status, the environment-match result. Point the contributor at `issue` (or, if work is
    underway, `verify`) — and if the SSH key is missing, name *that* as the first step.
    
    ## Writes — explicit confirmation only
    
    `setup` writes files **only** with explicit user confirmation and **only** within the
    target project. Show the contributor each file to be written before writing it. Never
    write outside the project directory.
    
    ## Detect-driven
    
    Every step checks first and does only what is missing. Re-running `setup` on a ready
    environment is a no-op that simply reports state.
    
    ## Examples
    
    ### Example 1: existing module, environment ready
    **Trigger:** `/drupal-ai-contrib:setup` in a contrib module that already has DDEV.
    **Actions:**
    1. Detect the workflow (someone else's contrib) and the GitLab issue system.
    2. DDEV already present → report it, do not re-create.
    3. Parse `.gitlab-ci.yml`, record the discovered gate set; environment-match the core.
    **Result:** No files written; the contributor is told to proceed to `issue`.
    
    ### Example 2: new module, maintainer setup
    **Trigger:** `/drupal-ai-contrib:setup` in a fresh contrib module with no CI config.
    **Actions:**
    1. Stand up DDEV with `ddev-drupal-contrib`.
    2. Show each scaffold file (`.gitlab-ci.yml`, `phpcs.xml.dist`, `phpstan.neon`,
       `phpunit.xml.dist`, `.cspell-project-words.txt`) and write only on confirmation.
    **Result:** A CI-ready module the maintainer owns.
    
    ## Troubleshooting
    
    | Situation | Handling |
    |-----------|----------|
    | `drupal_devkit` not installed | Report how to obtain it; do not block setup. |
    | `drupalorg` not on `PATH` | Surface `references/drupalorg-cli.md` (PHAR install); offer to install; do not block. If installed via Composer global, the bin dir may just be off `PATH` — see the reference's Install note. |
    | `glab` missing or not authenticated | Report it as a next step (install `glab`; `glab auth login --hostname git.drupalcode.org`); never block. Only migrated-project authenticated writes need it — `drupalorg` reads and the legacy queue work without it. See `references/drupalorg-cli.md` §Hybrid model. |
    | No SSH key registered on the drupal.org account | Guide the contributor to add one (*drupal.org → My account → SSH keys*); report it as the next step. Read/review still works; `git push` to issue forks does not. Never block. |
    | Workflow cannot be inferred | Ask the contributor — never assume core vs. contrib. |
    | `.gitlab-ci.yml` exists but uses a non-`gitlab_templates` setup | Record what is there; `verify` mirrors the discovered jobs as-is. |
    | Contributor declines a scaffold write | Skip that file; report which gates remain unconfigured. |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.