Agent skill
Create a transparent open-source contribution workflow in which agents may help prepare changes, but a human personally validates the result and owns the final request for review.
$ npx skills add c11dev/agents --skill human-validated-prs
Installs via the skills CLI — portable across Claude Code, Cursor, Codex, Copilot & Gemini.
SKILL.md
Skill definition and agent instructions.
references/templates.md
Reference file.
Create a transparent open-source contribution workflow in which agents may help prepare changes, but a human personally validates the result and owns the final request for review.
The policy is about accountable testing, not performative review. Do not require contributors to claim they inspected every line. Do not use embarrassing traps, false confessions, or punitive PR text.
Before editing, inspect the repository’s existing CONTRIBUTING.md, AGENTS.md, .github/pull_request_template.md, issue or PR templates, test instructions, and release rules. Preserve compatible project-specific guidance and terminology.
For a new policy, establish these boundaries:
Do not add an AI-disclosure requirement unless the repository owner requests one. Human accountability and validation are the default requirement.
Use the repository’s existing layout when present. The usual split is:
CONTRIBUTING.md — public contributor policy and validation expectations.AGENTS.md — operational instructions for coding agents..github/pull_request_template.md — concise human-validation checklist and a place to report evidence.Keep all three consistent. Do not hide a policy in AGENTS.md that contradicts the public contribution rules.
Adapt the templates in references/templates.md rather than replacing substantial existing documents wholesale.
Require validation appropriate to the change:
The human should report the commands run and/or behavior checked. Do not claim a human performed a check unless they explicitly confirm it.
If required validation cannot be performed, leave the PR as a draft and say what remains unverified. Do not present automated agent execution alone as personal human testing.
If the user explicitly insists that the agent create the PR after the policy is explained:
The hold notice is a workflow state, not a joke or punishment. It must remain truthful. If the human has already supplied and approved the final description and personally confirmed validation, do not claim that they have not.
Check for these failure modes:
Recommend the smallest edits that make the policy transparent and consistent.
Report:
# Human-Validated Pull Requests Create a transparent open-source contribution workflow in which agents may help prepare changes, but a human personally validates the result and owns the final request for review. The policy is about accountable testing, not performative review. Do not require contributors to claim they inspected every line. Do not use embarrassing traps, false confessions, or punitive PR text. ## Establish the repository policy Before editing, inspect the repository's existing `CONTRIBUTING.md`, `AGENTS.md`, `.github/pull_request_template.md`, issue or PR templates, test instructions, and release rules. Preserve compatible project-specific guidance and terminology. For a new policy, establish these boundaries: 1. AI-assisted contributions are allowed unless the owner says otherwise. 2. A human must personally test or otherwise validate the change before requesting review. 3. The PR description must state what the human validated and how. 4. An agent may prepare changes, commits, and draft PR text. 5. A human must provide the final description and mark the PR ready for review. 6. Creating a branch, pushing, or opening a PR is a public/external action and still requires explicit user approval immediately before it occurs. Do not add an AI-disclosure requirement unless the repository owner requests one. Human accountability and validation are the default requirement. ## Files and ownership Use the repository's existing layout when present. The usual split is: - `CONTRIBUTING.md` — public contributor policy and validation expectations. - `AGENTS.md` — operational instructions for coding agents. - `.github/pull_request_template.md` — concise human-validation checklist and a place to report evidence. Keep all three consistent. Do not hide a policy in `AGENTS.md` that contradicts the public contribution rules. Adapt the templates in [`references/templates.md`](references/templates.md) rather than replacing substantial existing documents wholesale. ## Human validation standard Require validation appropriate to the change: - Application or library code: personally run relevant automated tests and/or manually exercise the changed behavior. - UI changes: personally inspect the affected interface in addition to relevant automated checks. - Documentation: personally check rendering, links, examples, and formatting as applicable. - Configuration or packaging: personally exercise the relevant validation, build, install, or dry-run path where practical. The human should report the commands run and/or behavior checked. Do not claim a human performed a check unless they explicitly confirm it. If required validation cannot be performed, leave the PR as a draft and say what remains unverified. Do not present automated agent execution alone as personal human testing. ## Agent behavior when asked to create a PR 1. Prepare the changes, validation summary, and proposed PR description. 2. Explain that repository policy reserves the final description and readiness decision for a human. 3. Ask the user to review, personally test, and publish or mark the PR ready. 4. Do not push or create a PR without explicit approval for that specific external action. If the user explicitly insists that the agent create the PR after the policy is explained: - create **only a draft PR**; - use the neutral automated-draft hold notice from the template; - include useful implementation and automated-validation details below the notice when appropriate; - do not check human-validation attestations; - do not mark the PR ready for review; - tell the user they must personally test the change, replace the notice, complete the validation section, and mark it ready. The hold notice is a workflow state, not a joke or punishment. It must remain truthful. If the human has already supplied and approved the final description and personally confirmed validation, do not claim that they have not. ## Review an existing policy Check for these failure modes: - requiring an unverifiable claim that every line was reviewed; - treating agent-run tests as personal human validation; - allowing an agent to mark its own PR ready; - hidden instructions that publicly embarrass contributors; - false or misleading PR metadata; - contradictory rules across contribution, agent, and PR-template files; - no accommodation for documentation-only or otherwise non-runtime changes; - no clear path when testing cannot be completed. Recommend the smallest edits that make the policy transparent and consistent. ## Completion report Report: - files created or updated; - the human validation requirement; - what agents may prepare; - which actions remain human-controlled; - the draft fallback behavior and exact hold notice; - any project-specific test commands still needing confirmation.
Adapt these sections to the repository. Merge them into existing documents instead of duplicating headings or deleting project-specific guidance.
CONTRIBUTING.md## Human validation
AI-assisted contributions are welcome, but a human must personally validate the resulting change before requesting review. The pull request must describe what was tested and how.
Agents may prepare changes and draft pull request content. A human must provide or approve the final description, personally perform the appropriate validation, and mark the pull request ready for review.
Validation should fit the change. For example, code changes may require automated tests and manual behavior checks, while documentation changes may require checking rendered output, links, examples, and formatting. If the required validation has not been completed, keep the pull request in draft state and identify what remains unverified.
AGENTS.md## Pull requests
Agents may prepare changes, commits, validation summaries, and draft pull request text. Do not push a branch, create a pull request, or modify public repository metadata without explicit user approval for that specific action.
Repository policy requires a human to personally test or otherwise validate the change, provide or approve the final pull request description, and mark the pull request ready for review. Never claim that a human performed validation unless they explicitly confirm it.
When asked to create a pull request, explain this policy and offer a proposed description for the human to use. If the user explicitly authorizes the agent to create it anyway, create only a draft pull request with the automated-draft hold notice. Do not mark it ready for review or check any human-validation attestations.
Use this only while it is true:
> **Automated draft:** The submitting user has not yet provided the required human-reviewed description. Hold review until this notice is replaced and the pull request is marked ready.
Implementation details and agent-run checks may follow the notice, but they do not satisfy the human-validation requirement.
.github/pull_request_template.md## Summary
<!-- Explain the change and why it is needed. -->
## Human validation
- [ ] I personally validated this change.
- [ ] I described the validation I performed below.
- [ ] I replaced any automated-draft hold notice.
### Validation performed
<!-- List commands you personally ran and/or behavior you personally checked. -->
## Additional context
<!-- Risks, screenshots, follow-up work, or anything reviewers should know. -->
Do not pre-check these boxes. A human completes them before requesting review.
# Human-Validated PR Templates Adapt these sections to the repository. Merge them into existing documents instead of duplicating headings or deleting project-specific guidance. ## `CONTRIBUTING.md` ```md ## Human validation AI-assisted contributions are welcome, but a human must personally validate the resulting change before requesting review. The pull request must describe what was tested and how. Agents may prepare changes and draft pull request content. A human must provide or approve the final description, personally perform the appropriate validation, and mark the pull request ready for review. Validation should fit the change. For example, code changes may require automated tests and manual behavior checks, while documentation changes may require checking rendered output, links, examples, and formatting. If the required validation has not been completed, keep the pull request in draft state and identify what remains unverified. ``` ## `AGENTS.md` ```md ## Pull requests Agents may prepare changes, commits, validation summaries, and draft pull request text. Do not push a branch, create a pull request, or modify public repository metadata without explicit user approval for that specific action. Repository policy requires a human to personally test or otherwise validate the change, provide or approve the final pull request description, and mark the pull request ready for review. Never claim that a human performed validation unless they explicitly confirm it. When asked to create a pull request, explain this policy and offer a proposed description for the human to use. If the user explicitly authorizes the agent to create it anyway, create only a draft pull request with the automated-draft hold notice. Do not mark it ready for review or check any human-validation attestations. ``` ## Automated-draft hold notice Use this only while it is true: ```md > **Automated draft:** The submitting user has not yet provided the required human-reviewed description. Hold review until this notice is replaced and the pull request is marked ready. ``` Implementation details and agent-run checks may follow the notice, but they do not satisfy the human-validation requirement. ## `.github/pull_request_template.md` ```md ## Summary <!-- Explain the change and why it is needed. --> ## Human validation - [ ] I personally validated this change. - [ ] I described the validation I performed below. - [ ] I replaced any automated-draft hold notice. ### Validation performed <!-- List commands you personally ran and/or behavior you personally checked. --> ## Additional context <!-- Risks, screenshots, follow-up work, or anything reviewers should know. --> ``` Do not pre-check these boxes. A human completes them before requesting review.