Skip to content

docs: add agent guidelines, AI review stage and create-issue skill - #39

Closed
regislon wants to merge 1 commit into
collaboration-setupfrom
agent-guidelines
Closed

regislon wants to merge 1 commit into
collaboration-setupfrom
agent-guidelines

Conversation

@regislon

Copy link
Copy Markdown

Problem

Many PRs on this repo are prepared with AI coding agents, but nothing tells those agents how to work here: which rules apply, how to write PRs, how review works. This was split out of #35 so the contribution guide can land without settling the AI questions first.

Change

  • AGENTS.md: the rules from CONTRIBUTING written for AI coding agents (Claude Code, Codex, Copilot, …), plus working principles (think first, keep it simple, surgical changes, verify). It asks agents to disclose in the PR description that a PR was AI-prepared.
  • AI review stage in CONTRIBUTING: PRs prepared with agents get an AI review first, labelled llm-changes-needed or ready-for-human-review, then the human review from docs: add issue templates with a Done when section #35.
  • create-issue agent skill (.agents/skills/create-issue/): tool-agnostic Agent Skills format, linked into .claude/skills/ for Claude Code and referenced from AGENTS.md for other tools. A script reads the issue forms at runtime and renders a body identical to a browser submission; the skill searches for duplicates, has the user confirm Done when, and only creates the issue on a clear yes.
  • .gitignore keeps .claude/skills/ tracked (the rest of .claude/ stays ignored); mdformat-frontmatter added to pre-commit so skill frontmatter survives formatting.

Done when

Must have

  • The core team agrees on the AI rules (disclosure, two-stage review)
  • Maintainer creates the labels llm-changes-needed and ready-for-human-review

Nice to have

  • Shared create-issue agent skill
  • More shared agent skills (create/sync PR, commit-and-push, review-pr)

Testing

  • pre-commit passes on all changed files.
  • create-issue render script tested on our fork: full render, missing required fields, unknown field, unknown template. Claude Code discovers the skill through the symlink; Codex / Gemini / Cursor discovery of .agents/skills/ not tested. No real issue was created.

Impact on outputs

None.

Dependencies

Builds on #35 and targets its branch; it retargets to main once #35 merges. Open questions for the team:

  • AI attribution: keep the disclosure rule, drop it, or change it?
  • Review flow: do you want the AI review stage, or only human review?

Prepared with Claude Code (Claude Opus 5.5).

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant