Work with AI

Artemis agent skills provide repository-specific procedures for testing, CI, migrations and development.

Shared instructions and task-specific skills

AGENTS.md contains shared rules and links to skills. Codex reads it directly. CLAUDE.md contains only @AGENTS.md, so Claude Code loads the same rules through its documented import. Do not copy the rules into CLAUDE.md or import the skills there.

Claude Code can also read AGENTS.md directly, but versions before 2.1.281 could silently skip it when telemetry was disabled or the session used Bedrock. The import keeps the shared rules available in those sessions without requiring telemetry. In Claude Code, use /memory or /context to check which instruction file loaded.

Skill discovery exposes names and descriptions; the agent reads a selected SKILL.md and its references as needed. Ordinary Markdown links do not install skills or import their contents. They let an agent read the checked-in procedures without installation. Do not @-import skills into an instruction file: imports load at startup rather than on demand. See the Agent Skills specification and Codex skill documentation for discovery behavior.

Preparing Pull Requests with an Agent

Coding agents follow the same PR readiness requirements as human authors. When creating or updating a PR, have the agent clean up the template, check only work actually completed, remove inapplicable tasks and empty sections, and set the intended release milestone. Keep pending validation and applicable review tasks unchecked until the checks, reviews or tests take place. Use drafts only for unfinished implementations. Open completed work as non-draft or mark it ready for review immediately, so full CI and automated review bots run. Pending CI, reviews or test-server validation do not require draft status; all merge requirements still apply. Keep ready for review / ready to merge labels accurate after updates.

An agent must not invent test results, reviewer approvals or a release target. If it cannot edit PR metadata or determine the milestone, it reports the missing action and requests maintainer help. The shared rules in AGENTS.md make this part of every PR task, independent of the implementation skill.

Installing

Skills CLI

npx skills add ls1intum/Artemis

Select your agent in the skills CLI. Installation locations and invocation syntax depend on the agent.

Claude Code

For Claude Code, prefer the namespaced plugin over the Skills CLI:

/plugin marketplace add ls1intum/Artemis --scope local
/plugin install artemis@artemis --scope local

The local scope enables the plugin only in this checkout, without shared settings changes. The plugin distributes skills, not repository memory files. Installing it in another repository does not load Artemis's AGENTS.md.

The skills then appear as /artemis:e2e-pr-check, /artemis:ci-triage, and so on. Claude can also select them automatically from their descriptions; selection is not guaranteed.

Use one installation method per agent to avoid duplicate skill entries. Plugin names such as /artemis:ci-triage distinguish these skills from personal skills with the same short name.

Working on the skills themselves

claude --plugin-dir .

Run from the repository root to load this checkout rather than an installed copy. For Codex:

npx skills add . --agent codex --skill '*' --copy --yes

This installs every skill from the working tree. Repeat after editing them to refresh the installed copies. Local skill files and skills-lock.json are ignored by Git; edit skills/, not .agents/skills/. Use npx skills list --agent codex to check discovery.

The skills

Skill	Use it when
e2e-pr-check	You need to select, run, write or debug Playwright tests
ci-triage	A pull request is red, or a check never appeared
server-arch-gates	You changed server Java or need to diagnose an ArchUnit violation
liquibase-migration	You are adding, changing, or dropping anything in the database schema
client-conventions	You are writing or migrating Angular code
write-tests	You are adding a JUnit test or a Vitest spec
local-setup	You are setting up from a fresh clone, or something will not start

Invoke a Claude plugin skill with /artemis:ci-triage; in Codex, use $ci-triage or /skills. Agents can also select skills automatically from their descriptions.

Checking skill behavior

Use a fresh agent session after changing shared instructions. In Claude Code, inspect /memory or /context to confirm that CLAUDE.md loaded and imported AGENTS.md. In Codex, ask which repository instructions and skills are available. When testing edits to a skill, confirm the agent reads this checkout rather than an older installed copy; claude --plugin-dir . loads the working plugin directly.

Compare representative tasks before and after an instruction change with the same model, settings and repository state. Include both matching tasks and tasks that should not use a skill:

Request	Expected behavior
Fix a typo in documentation	No server, client or E2E procedure is needed
Migrate an Angular component to signal inputs	Use client-conventions; load migration examples when needed
Add a Vitest regression test	Use write-tests and its client reference, not the server reference
Explain why a CI check never started	Use ci-triage, not a speculative code fix
Add a NOT NULL database constraint	Use liquibase-migration and check data and rollback requirements
Run affected E2E tests with uncommitted changes	Use e2e-pr-check; disclose the resolver's committed-diff limitation without making an unsolicited commit

Record which files were loaded, whether the task succeeded, the checks run and unnecessary work. Skill selection is model-dependent: a valid file or a successful path check does not prove useful routing or better outcomes. Skill instructions do not grant permission to commit, deploy or alter services.

Contributing a skill

A skill is a directory under skills/ with a SKILL.md and optional reference/ files:

skills/
  my-skill/
    SKILL.md
    reference/background.md

---
name: my-skill
description: What it does and when to use it, key use case first.
---

# Title

The procedure.

Use a short description of the task that should trigger the skill, not a contents list or promise of success.

1. Cite repository paths for non-obvious facts. supporting_scripts/check_skill_references.py runs in the Agent Skills CI job. It checks recognized path-shaped tokens in inline code and fenced blocks, not every Markdown link or the truth of the surrounding claim. Review linked files and command behavior separately.
2. Route the new skill. The same check requires a link from AGENTS.md and from the skill table above, so agents reach the skill without installing anything. It also rejects frontmatter that agents cannot index: the name must match the directory and the description must be present.
3. Keep the body focused. Put substantial conditional detail in linked reference/ files.
4. Explain non-obvious constraints. Include the reason when it prevents a plausible but incorrect alternative.
5. Do not duplicate AGENTS.md or other skills. Keep shared constraints in the entry point, procedures in the matching skill, and conditional detail in linked references. Preserve non-obvious Artemis constraints rather than deleting them to meet a line-count target.

Validate the files and run the behavioral checks:

python3 supporting_scripts/check_skill_references.py
python3 supporting_scripts/check_skill_references.py --self-test
claude plugin validate .
claude plugin validate .claude-plugin/plugin.json

When publishing skill changes, bump version in .claude-plugin/plugin.json in the same pull request. Claude Code uses that version to identify updates; unchanged versions can leave users on cached instructions. After merging, plugin users can run /plugin marketplace update artemis and /plugin update artemis@artemis --scope local, then restart Claude Code. See plugin version management.

Update the skill when its cited code or convention changes.