Acquia Skills for coding agents

Acquia Skills is entitlement-gated

Acquia Skills is available only to Cloud Platform Enterprise and Site Factory plans; Multi-Experience Operations does not support it. Check your subscription’s entitlement before you install: acli api:subscriptions:list prints the subscriptions your account can see, and acli api:subscriptions:entitlements-list <subscription-uuid> prints what one of them is entitled to. On other plans the skills won’t do anything useful.

Goal: run Cloud Platform operations (deploys, database syncs, log diagnosis) from an agentic CLI in natural language, by installing Acquia Skills.

Skills are guidance artifacts, not enforcement tools: machine-readable files bundling Acquia’s operational best practices and procedural safety policies. Your agent reads them to map an intent like “deploy my branch to Stage” onto the correct acli command, parameter, or API call. They rely entirely on your existing infrastructure permissions: an agent cannot execute a skill-based action unless you already hold the underlying credentials (SSH keys, API tokens) for that environment.

What you’ll have when you’re done

• Acquia Skills installed in your project and loaded into your agent’s context.
• One platform operation performed from a natural-language prompt.
• The same pattern working inside Cloud IDE via BYOAI.

Prerequisites

• A Cloud Platform Enterprise or Site Factory subscription (see the caveat above).
• An agentic CLI: Claude Code is used in the examples; any agent that reads plain text or markdown works.
• Working Acquia credentials on the machine the agent runs on: skills use your existing local credentials and never store or manage API keys. The CLI quickstart covers authenticating acli.
• Node.js, for npx.

Steps

1. Install the skills

   In your project directory:

   npx skills add acquia/acquia-skills

   The skills CLI (an npm package npx fetches on first use) clones the official acquia/acquia-skills repository and installs its 14 skills into your project. In an interactive terminal the CLI first prompts for scope (project or global) and confirmation; when it detects an agent session (or you pass -y) it installs non-interactively:

   ●  claude-code_2-1-200_agent  Agent detected — installing non-interactively
   ◇  Source: https://github.com/acquia/acquia-skills.git
   ◇  Repository cloned
   ◇  Found 14 skills
   ●  Installing all 14 skills
   ◇  72 agents
   ●  Installing to: Antigravity, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot
   ◇  Installation complete
   ◇  Installed 14 skills
   └  Done!  Review skills before use; they run with full agent permissions.

   The 14 skills are: application-management, codestudio, environment-management, getting-started, ide-management, pull-push, remote-access, scripting, ssh-key-management, troubleshooting, dependency-updates, security-updates, pipeline-operations, and drupal-update-deploy. The repository is worth a browse if you want to inspect what your agent will be reading. Skill versions align with major releases of Acquia CLI and Pipelines CLI, so keep them updated alongside your tooling.

2. Load the skills into your agent’s context

   Agents that discover skills automatically (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and others) pick up the ./.agents/skills/ directory on their next session in the project: no extra step. For an agent without skill discovery, reference the files directly: @.agents/skills/<skill-name>/SKILL.md in Cursor, or upload the relevant SKILL.md files to a Claude project.

3. Run a natural-language platform operation

   Ask for the outcome, not the command:

   > Deploy the feature-login branch to the Stage environment.

   The agent uses the skills to identify the correct CLI command or API call, shows you what it intends to run, and executes it with your credentials. Other operations the skills cover:

   • Manage environments and applications.
   • Deploy code and synchronize databases.
   • Trigger builds and stream logs to diagnose failures: e.g. “Diagnose why the last pipeline build failed and fix the PHP linting error.”
   • Manage Drupal dependencies and security updates.
   • Manage IDE and developer workflows.

   For destructive or irreversible operations (database trims, environment wipes, production deployments), the skills instruct the agent to pause and request your explicit approval first, and they weigh environment impact (dev versus prod) before proposing an action. Agents can occasionally hallucinate file paths or parameters, so review the proposed command before you grant that confirmation: you are responsible for what the agent does with your credentials.

4. Use BYOAI inside Cloud IDE

   Cloud IDE’s Bring Your Own AI (BYOAI) feature runs the same pattern in the browser-based IDE. The steps below assume a running Cloud IDE (see Acquia’s Cloud IDE documentation for adding one to your subscription and creating it) with its AI features switched on and a provider key entered. Then, in the IDE terminal:

   1. Install your preferred agent’s CLI and provide its API key: for example, npm install -g @google/gemini-cli for the Gemini CLI, entering the key when prompted.
   2. Add the skills: npx skills add acquia/acquia-skills
   3. Prompt the agent, referencing the skills, for example: “refer to skills and update the package using composer.” The agent uses the Acquia Skills library to execute the correct commands in the environment.

What just happened

Your agent didn’t get new powers: it got documentation it can act on. Acquia publishes the skills following the emerging standards for agentic discovery: an llms.txt index gives the model a concise map of available tools, and AGENTS.md defines the behavior, constraints, and instructions for agents interacting with the Acquia ecosystem. Because skills are plain markdown, they work with any compliant agent. Because they carry no credentials, everything still runs under your existing Cloud Platform permissions (including Production Mode, which skills cannot bypass): if the API locks an environment, the agent cannot overwrite it.

When something goes wrong

npx: command not found

Node.js isn’t installed (or isn’t on PATH) where the agent runs. Install Node.js, then re-run step 1.

Operations fail with 403 Forbidden from the Cloud Platform API

the skills installed fine, but skills grant no permissions: your authenticated user lacks access to that application or environment. Fix the underlying credential (re-authenticate acli, or check your role on the application; roles and permissions are covered at docs.acquia.com), not the skills.

The agent reports the environment is locked and refuses to deploy

that’s Production Mode doing its job at the API level; skills cannot bypass it. Deploy to a non-production environment, or have an authorized user lift Production Mode deliberately.

The agent ignores the skills and improvises commands

the skills file isn’t in its context. Re-do step 2 for your agent (attach with @ in Cursor, upload to the Claude project, or reference the file explicitly in the prompt, e.g. “refer to skills”).

Next steps

• Acquia’s Cloud IDE documentation: what a Cloud IDE is, adding one to a subscription, and creating your first one.
• Everyday workflows with acli: the commands your agent is choosing between, worth knowing yourself.
• Connect an AI agent via MCP: agents operating on content, where skills operate on the platform.