qubership-ai-packages: Skill for Claude Code

Authoring APM packages

APM is a package manager for AI-agent primitives: instructions (always-on rules), skills (on-demand how-to guides), prompts (user-invoked slash-commands), agents (sub-agent personas with tool boundaries) and hooks (lifecycle scripts). A platform can ship its conventions as APM packages so service developers receive them as apm dependencies and agents like Claude Code, Copilot and Cursor pick them up natively.

This skill is the contract between library authors and the agents that read their packages. Apply it whenever you touch apm.yml, anything under a .apm/ tree, or set up a new agent-packages/<name>/.

Package layout

A library repo can host one or more APM packages. Each one lives under agent-packages/<package-name>/ so the path itself is the disambiguator:

agent-packages/
└── <package-name>/                  # = `name:` in apm.yml
    ├── apm.yml
    └── .apm/
        ├── instructions/            # *.instructions.md — always-on rules
        │   └── <package-name>.instructions.md
        ├── skills/                  # SKILL.md — on-demand how-tos
        │   └── <package-name>/
        │       └── SKILL.md
        ├── prompts/                 # avoid — Codex skips prompts; use a user-invoked skill
        │   └── <name>.prompt.md
        ├── agents/                  # optional — *.agent.md, sub-agent personas
        │   └── <name>.agent.md
        └── hooks/                   # optional — lifecycle scripts

Rules:

• <package-name> is descriptive and unique (context-propagation-go-usage, hardened-dockerfile-usage), not a generic placeholder like user-guide. Multiple packages can sit side-by-side in one repo, so the directory name has to identify the package on its own.
• A package holds a coherent set of primitives (instructions, skills, prompts, agents, hooks) that share an audience and a trigger surface (e.g. <lib>-usage for day-to-day code; a separate <lib>-troubleshooting if the failure-mode catalogue is large enough to deserve its own activation). Bundle by topic, not by file count — a one-skill package and a five-skill package are both fine if each set is internally coherent.
• An auto-triggered skill needs a paired instructions file. Without the trigger merged into AGENTS.md / CLAUDE.md the agent has no signal to pull the skill in. Keep names aligned so the link is obvious from the tree. Two cases need no instruction: a small always-true rule may ship as a standalone instruction with no skill behind it (see next section), and a user-invoked skill — the replacement for a slash-command — carries its activation rule in its own description:, so the user invokes it by name and no paired instruction is needed (see "Agents, hooks, and prompts").