adcm-agent: Instructions file for Claude Code

Authoring contract

How skills, commands, agents and scripts in this repository are written. Read this before adding or editing one. tools/validate_skills.py and tools/check_scripts.py enforce the mechanical half; the rest is style you are expected to match by hand.

Repository layout

.claude-plugin/
  plugin.json          # every skill directory must be listed in skills[]
  marketplace.json     # one plugin entry, source "./"
skills/<skill-name>/
  SKILL.md             # required
  reference/*.md       # optional: lookup material (tables, inventories, key lists)
commands/*.md          # slash commands
agents/*.md            # subagents
scripts/               # what the skills actually run - shipped to users
tools/                 # this repository's own validation - not shipped as behaviour

Skill directories are kebab-case and always prefixed adcm-. SKILL.md is always uppercase. Commands are prefixed adcm- too, so they read as /adcm-build.

The rule this repository exists to enforce

No file here may contain a real ADCM instance address, account, credential or host name. Not in a skill, not in a command, not in a script default, not in a docstring, not in an example.

This is not a style preference. The skills this plugin replaces defaulted to one development stand's IP address and to admin/admin, which made them wrong for every other installation and put a credential in three git repositories. Everything instance-specific resolves at run time through scripts/adcm_env.py.

Both validators check this, and they check prose as well as code:

• a literal IPv4 address that is not loopback or an RFC 5737 documentation range
• an os.environ.get("ADCM_*", "<fallback>") with a baked-in default
• a default account pair used as a value
• a credential-looking assignment whose value is not a placeholder or an env var name

Write <ask the user>, $ADCM_URL, MY_VAR, adcm.example.internal instead.

Frontmatter

---
name: adcm-<topic>               # must equal the directory name
description: <what it does> - <inventory of the concepts it covers>. Use when <trigger>, <trigger>, or <symptom>.
license: Apache-2.0
metadata:
  author: Arenadata
  version: "0.1.0"
  adcmVersion: "2.x (API v2)"
---