Draft: AI Agents: add AI Agents configuration, hooks, and skills (claude) (!2013) · Merge requests · nexedi / slapos

Cédric Le Ninivin requested to merge cedric.leninivin/slapos:claude-code-v0 into master Mar 12, 2026

What this MR adds

Vendor-neutral agent configuration for the slapos repository, plus the first batch of skills wrapping common SlapOS workflows.

AGENTS.md — substance file, read by any agent following the agents.md spec (OpenAI Codex, OpenCode, Aider, Gemini CLI, Cursor, GitHub Copilot, Block Goose, …). Holds the project guide: environment, testing, architecture, build, deploy, code style, git push safety.
CLAUDE.md — thin Claude-Code-only shim. @AGENTS.md imports the substance; the rest is Claude-Code-specific slash-command shortcuts and a Bash-hang environment note.
.claude/skills/<name>/SKILL.md — skills in the open Agent Skills format (name + description YAML frontmatter + markdown body). Read natively by Claude Code, OpenCode, Codex, Gemini CLI, Goose, and other Agent-Skills-compatible agents.
.claude/settings.json + hook scripts — Claude-Code-specific runtime (PreToolUse / PostToolUse hooks for hash updates, rebuild/reprocess reminders, coding-rules checks). Cross-tool hook porting is not yet in scope.
.claude/env.local.json.example — template for machine-specific paths (not committed in real form).

Why this shape — the standards landscape, May 2026

Concept	Spec	Governance	Adoption
Project guide	`AGENTS.md`	Agentic AI Foundation / Linux Foundation	60K+ projects
Capability packaging	`SKILL.md` / Agent Skills	Anthropic open spec; not yet AAIF	~32 tool vendors in 90 days
Tool protocol	MCP	AAIF	broad
Vendor-specific (legacy)	`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`	per-vendor	tied to one tool

Tool-by-tool compatibility

Tool	`AGENTS.md`	`CLAUDE.md`	`.claude/skills/`
Claude Code	via `@AGENTS.md` import (Anthropic's recommended bridge)	✅ native	✅ native (original SKILL.md impl)
OpenAI Codex CLI	✅ native	only with `project_doc_fallback_filenames` opt-in	✅ native (`developers.openai.com/codex/skills`)
OpenCode	✅ native	✅ fallback	✅ native (looks in `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`)
Gemini CLI	✅ native (via `.gemini/settings.json`)	❌	✅ native (Agent Skills)
Aider	✅ native (via `.aider.conf.yml: read: AGENTS.md`)	❌	❌
Block Goose	(manual)	❌	✅ native (coexists with pre-existing Recipes YAML)
Cursor / Copilot / Junie / Kiro / Amp / TRAE / Letta / etc.	✅ via AGENTS.md adoption	❌	✅ via Agent Skills

Why both `AGENTS.md` and `CLAUDE.md`?

Claude Code does not yet auto-read AGENTS.md. Anthropic's recommended bridge is a thin CLAUDE.md that begins with @AGENTS.md, which Claude Code inlines on session start. That keeps a single source of truth (AGENTS.md) for all other agents while still letting Claude Code see the same project guide.

Open governance question

SKILL.md is the open spec but is not yet AAIF-stewarded — Anthropic released it 9 days after anchoring AAIF with MCP, and kept it outside the Foundation. The AAIF's three founding projects (Dec 9, 2025) are MCP + Goose + AGENTS.md; Skills is absent. Worth watching whether Skills follows the AGENTS.md path to neutral governance.

Skills in this MR

Skill	Description
`/add-component`	Add a Component (external binary/library) to a Software Release
`/add-frontend`	Request an IPv4 Frontend (public HTTPS URL) for a Service
`/add-logrotate`	Add Logrotate for a Service
`/add-monitoring`	Add the Monitoring Stack to a Software Release
`/add-parameter`	Add an Instance Parameter (slapparameter)
`/add-promise`	Add a SlapOS Promise
`/add-service`	Add a Service to a SlapOS Instance
`/add-template`	Add a Jinja2 Template to a Software Release
`/rebuild-software`	Rebuild a SlapOS software release (kill existing process, `slapos node software --force`)
`/reprocess-instance`	Reprocess SlapOS instances (`slapos node instance --force`)
`/slapos-status`	Show SlapOS proxy status — software releases, partitions, connection parameters
`/run-sr-test`	Run a software release integration test with proper environment setup
`/inspect-logs`	Inspect SlapOS build and instance logs for errors and debugging
`/test-results`	Fetch test results for a git commit from ERP5's `test_result_module`
`/deploy-instance`	Deploy a new SlapOS instance (inspect schema, generate request, verify)
`/destroy-instance`	DANGEROUS — irreversibly destroys a SlapOS instance
`/show-instances`	List deployed instances for a software release with connection parameters
`/export-request-scripts`	Generate request scripts for all top-level instances

Contributor guidance

Prose conventions → AGENTS.md.
New skills → .claude/skills/<name>/SKILL.md with at least name: and description: frontmatter. They will work in any Agent-Skills-compatible agent, not just Claude Code.
Avoid adding to CLAUDE.md unless the content is genuinely Claude-Code-specific (slash-command UX, hook references, etc.).

Test plan

Skills appear in Claude Code's skill listing
/run-sr-test rapid-cdn test.TestMasterRequest loads correctly
/show-instances erp5-mcp-hateoas loads correctly
Editing a software/*/ file triggers the update-hash PostToolUse hook
@AGENTS.md import resolves in Claude Code (substance is loaded)
add-*/SKILL.md files have valid name: / description: YAML frontmatter

Sources

agents.md — multi-vendor origin, AAIF governance, 60K+ projects
agentskills.io — SKILL.md spec, 32 adopters in 90 days
AAIF founding press release (MCP + Goose + AGENTS.md)
addyosmani/agent-skills — practitioner flagship, ~41K stars

Replaces MR !2008 (closed) (closed — wrong source_project_id).

Edited May 14, 2026 by Cédric Le Ninivin

Draft: AI Agents: add AI Agents configuration, hooks, and skills (claude)