AI Agent Skills

This module ships AI-agent skills: small, structured instructions that a contributor’s AI coding agent picks up when working in the repo. They encode how to do specific module-development tasks correctly, so an agent (and the person guiding it) doesn’t have to rediscover the module’s conventions each time.

The convention follows the flagship Drupal AI module.

Where skills live

Skills live at the module root, one directory per skill:

.agents/skills/<name>/SKILL.md

Each SKILL.md uses the Agent Skills format — YAML frontmatter with a name and a description, followed by Markdown instructions:

---
name: contribute-to-the-module
description: What the skill does and when an agent should use it.
---

# Title

Focused instructions for the task…

The name matches the directory name; the description says when an agent should reach for the skill (this is what an agent scans to decide relevance).

Skills ship with the module

Unlike the docs site and the agent-guidance files, .agents/skills/ is not export-ignored — it is included in the packaged release. Anyone who installs the module (and their coding agent) gets the skills. This is deliberate; keep it that way.

Asset	Location	Ships in the release?	Purpose
Skills	.agents/skills/	Yes	Reusable, task-specific module-development instructions for agents
Agent guidance	AGENTS.md / CLAUDE.md	No (dev-only)	Repo-wide contribution guardrails, auto-loaded by AI coding tools
AI pipeline	playbook/	No (dev-only)	The team’s process framework (see the AI Pipeline page)

Name-collision warning: .agents/ (the skills directory, which ships) is easy to confuse with AGENTS.md (the root agent-guidance file, which is export-ignored). Never add .agents/ to the export-ignore list — that would silently stop the skills shipping.

How to add a skill

1. Create .agents/skills/<name>/SKILL.md with a name (matching the directory) and a description that states when to use it.
2. Write focused, imperative instructions for the one task. Point at the docs for details that change (setup commands, workflow) rather than duplicating them, so the skill can’t drift.
3. Keep each skill narrow — one task per skill (e.g. “contribute to the module”, or later, “create a new plugin of type X”).
4. Commit it through the normal issue-fork → merge-request workflow.

Skills vs. the other AI assets here

• Skills (.agents/skills/) — ship; reusable module-development tasks (this page).
• Agent guidance (AGENTS.md / CLAUDE.md) — dev-only; the non-negotiable contribution rules an AI tool loads automatically.
• AI pipeline (playbook/) — dev-only; the broader process framework.

For where each file format belongs and how these pages are edited, see Choosing a Page (File) Format and Developer Setup.