adcm-agent

ADCM agent skills

Agent skills and a Claude Code plugin for Arenadata Cluster Manager — the platform that turns a bundle into a running cluster.

An agent reasoning about an ADCM bundle from general Ansible intuition gets things confidently wrong: it edits a generated file that the next version bump silently reverts, mixes build-time Jinja with runtime Ansible Jinja, combines states: and masking: on one action, reads an upload rejection as a tooling problem rather than as the test result it is, or deletes somebody else's bundle to clear a version collision. These skills encode what actually matters — the DSL semantics, the packer contract, the operational traps and the exact commands.

They work against any ADCM installation and any bundle repository. Nothing here carries an instance address, an account, a credential or a host name; a validator in CI fails the build if one appears.

Install

/plugin marketplace add arenadata/adcm-agent
/plugin install adcm@adcm-agent-skills

From a local checkout:

/plugin marketplace add /path/to/adcm-agent
/plugin install adcm@adcm-agent-skills

Then point it at your instance — /adcm-connect walks through it, or write the config directly:

# ~/.config/adcm-agent/config.yaml   (chmod 600)
default_profile: dev
profiles:
  dev:
    url: https://adcm.example.internal:8443
    user: your-login
    password_command: "pass show adcm/dev"

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adcmctl.py" whoami

Skills load on demand — only their names and descriptions sit in context until one is relevant. Every skill also reads as plain documentation, so skills/<name>/SKILL.md is worth opening directly.

Skills

Commands

Subagents

Scripts

The skills drive four scripts at ${CLAUDE_PLUGIN_ROOT}/scripts/. They take the repository from the working directory, so run them from inside a bundle repo.

Everything they write goes to <repo>/.adcm/ — build output, staging, and a mode-600 state.json. Add .adcm/ and .adcm.yaml to your bundle repository's .gitignore.

Nothing is hardcoded, and that is enforced

Connection settings resolve, per field, from the first of: a CLI flag, an environment variable, <repo>/.adcm.yaml, ~/.config/adcm-agent/config.yaml. There is no default URL and no default account — a missing setting produces an error naming the setting and where it can come from, rather than a request to somebody else's stand.

Beyond that:

• A plaintext credential is read from a config file only if git would not commit it.
• Tokens cache in ~/.cache/adcm-agent/, keyed by URL and account, never in the repository.
• Passwords are never written anywhere. --set-env and --gen-secret keep them out of argv, which is world readable through /proc.
• delete-bundle and delete-cluster refuse anything this checkout did not create.

tools/validate_skills.py and tools/check_scripts.py fail the build on a literal IP address, a default account pair, an environment lookup with a baked-in fallback, or a credential-shaped literal — in code, in docstrings and in prose.

Use it on pull requests

The plugin can review bundle changes in place. Add a workflow that installs it from this marketplace, and Claude answers when someone writes @claude on a PR:

# .github/workflows/claude.yml
name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          plugin_marketplaces: "https://github.com/arenadata/adcm-agent.git"
          plugins: "adcm@adcm-agent-skills"
          claude_args: |
            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr comment:*),Read,Grep,Glob,Agent,Skill"

Then comment @claude review this bundle change — or name the reviewer explicitly with @claude @agent-adcm:adcm-bundle-reviewer review this.

Two things worth knowing. The plugin_marketplaces URL must end in .git; the action rejects owner/repo shorthand and SSH URLs. And the inline-comment MCP server only starts when claude_args names mcp__github_inline_comment__create_inline_comment, so keep that entry even though the review flow implies it.

A repo-level CLAUDE.md telling Claude to delegate to @agent-adcm:adcm-bundle-reviewer makes a bare @claude review this route correctly without anyone remembering the agent's name.

Reviewing a bundle change needs no ADCM instance. Deploying does, and CI has no credentials — keep /adcm-deploy out of automated workflows.

Scope

These skills cover developing and operating ADCM bundles: building them, validating them, authoring their DSL and their actions, and deploying a cluster to test them. Installing and administering ADCM itself — the container, the database, the role model, LDAP, backups — is the ADCM documentation's subject, not this plugin's.

Contributing

Read AGENTS.md — it is the authoring contract: structure, frontmatter, voice, grounding rules, and the no-hardcoded-environment rule that everything else rests on. Then:

python3 tools/validate_skills.py     # structure, frontmatter, links, manifests, leaks
python3 tools/check_scripts.py       # scripts parse, self-describe, carry no defaults
python3 tools/check_doc_links.py     # external documentation URLs (needs network)

If you changed anything under scripts/, run it against two different bundle repositories before opening the PR.

License

Apache-2.0. See LICENSE.