How the PR Metadata Convention Identifies Agent Work in humanlayer/skills

The PR metadata convention in humanlayer/skills uses a standardized trio of label names, title prefixes, and branch prefixes to automatically detect, bound, and iterate on agent-generated pull requests.

The humanlayer/skills repository defines a strict PR metadata convention that every automated agent must follow when creating pull requests. This convention enables GitHub Actions workflows to recognize their own output, prevent duplicate work, and securely process reviewer feedback without manual bookkeeping. By standardizing how agents label, title, and branch their contributions, the system maintains clear boundaries between automated and human-generated code.

The Three Components of the PR Metadata Convention

Label Name for Automated Filtering

Every agent loop assigns a unique label following the pattern agent-<task-slug>. According to plugins/design-control-loop/skills/design-control-loop/SKILL.md, this label allows the control loop to query GitHub's API for existing work using commands like gh pr list --label "$AGENT_LABEL" --state open. The label serves as the primary key for identifying all pull requests created by a specific agent workflow.

PR Title Prefix for Human Readability

The convention requires PR titles to follow the template [MM/DD][Agent: <Agent Name>]: <Concise Description>, as documented in plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md at lines 49-51. This format immediately signals to human reviewers that the change originated from an automated agent and identifies which specific task or migration the agent is executing.

Branch Prefix for Source Tracking

Agent-generated branches use the format <branch-prefix>/$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT, implemented in plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml at lines 98-106. This naming convention embeds the GitHub Actions run ID directly into the branch name, making it trivial to correlate a pull request with its originating workflow execution using standard git commands.

Bounding and Iterating on Agent Workflows

Preventing Duplicate PRs with Label Gates

Before each scheduled run, the workflow executes a bounding check to prevent an avalanche of unreviewed pull requests. The implementation in references/workflow-template.yml (lines 55-62) queries for existing open PRs:

- name: Check iterate marker to bound work-in-progress
  id: agent_gate
  env:
    AGENT_LABEL: agent-<task-slug>
  run: |
    if [ "$EVENT_NAME" = "schedule" ]; then
      EXISTING_PR=$(gh pr list --label "$AGENT_LABEL" --state open --json number,url --limit 1)
      if [ "$(echo "$EXISTING_PR" | jq 'length')" -gt 0 ]; then
        echo "run_agent=false" >> "$GITHUB_OUTPUT"
        exit 0
      fi
    fi
    echo "run_agent=true" >> "$GITHUB_OUTPUT"

If the query returns any open PRs with the agent's label, the workflow sets run_agent=false and exits as a no-op. This ensures only one active PR per agent task exists at any given time.

Securing Iteration with Hidden Markers

When a maintainer comments /iterate on a pull request, the workflow validates both the PR label and a hidden HTML comment marker before proceeding. The marker <!-- codelayer-agent:workflow=… --> is embedded in the PR body during creation, as implemented in references/workflow-template.yml at lines 71-84. This verification ensures that only the originating agent loop processes feedback commands, preventing accidental execution on human-created PRs or PRs from other agent workflows.

Branch Creation and Naming

When the workflow creates a new branch for agent work, it uses the standardized prefix to ensure traceability:

- name: Configure git user & branch
  if: steps.agent_gate.outputs.run_agent == 'true'
  run: |
    BRANCH="<branch-prefix>/$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
    git checkout -b "$BRANCH"

This approach allows developers to quickly locate the source branch of any agent PR using git checkout <branch-prefix>/… patterns.

Summary

• Label naming (agent-<task-slug>) provides the primary filtering mechanism for bounding open work and preventing duplicate pull requests.
• Title prefixes ([MM/DD][Agent: <Agent Name>]: …) deliver immediate visual indication to human reviewers that a PR was generated by an automated agent.
• Branch prefixes (<branch-prefix>/…) embed workflow run metadata directly into git references, enabling precise debugging and correlation.
• Hidden HTML markers (<!-- codelayer-agent:workflow=… -->) secure the iteration loop by cryptographically binding feedback commands to specific agent instances.

Frequently Asked Questions

What is the exact label format required by the PR metadata convention?

The label must follow the pattern agent-<task-slug>, where <task-slug> is a unique identifier for the specific agent workflow or task. This format enables precise filtering via GitHub's CLI (gh pr list --label) and API, allowing workflows to detect their own open pull requests before creating new ones.

How does the convention prevent multiple agents from creating duplicate PRs?

The workflow checks for existing open PRs with the specific agent label before execution. If any open PRs are found, the run becomes a no-op by setting run_agent=false and exiting immediately. This bounding mechanism, implemented in references/workflow-template.yml, ensures that only one active PR per agent task exists at any time, preventing repository clutter.

Can humans manually create PRs that participate in the agent iteration loop?

While humans can technically create PRs with matching labels, the iteration safety mechanism prevents unauthorized access. When a maintainer runs /iterate, the workflow verifies the presence of a hidden HTML comment marker <!-- codelayer-agent:workflow=… --> embedded in the PR body. Human-created PRs lacking this marker fail validation, ensuring only genuine agent-generated PRs can trigger automated iteration workflows.

Where are the specific PR metadata requirements documented in the repository?

The core convention is defined in plugins/design-control-loop/skills/design-control-loop/SKILL.md, with concrete title formatting examples provided in plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md at lines 49-51. The actual implementation logic, including label checking and branch naming, resides in plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}