agent-feedback

agent-feedback

When an agent detects a problem in a skill or agent definition during real use, that observation is valuable. This skill describes when and how to file a GitHub issue so it isn't lost.

When to apply

File an issue when you notice:

• A skill instruction didn't match what actually happened (divergence between the documented pattern and real behavior)
• A cross-link in a skill or agent body is broken or points to a renamed file
• A common situation that arose during the task isn't covered by the relevant skill
• A pattern in a skill is outdated (references stale tooling, superseded commands, or a deprecated execution shape)

Do NOT file for stylistic preferences or minor wording nits.

Threshold

File when either condition is true:

• (a) Divergence -- you followed a skill's instructions and behavior was wrong or the outcome differed from what the skill described
• (b) Gap -- a real situation arose that the skill doesn't cover and the omission caused uncertainty or a workaround

If neither condition applies, continue without filing.

Title format

fix: <skill-name> -- <one-line description>
feat: <skill-name> -- <one-line description>

Use fix: for incorrect or outdated instructions. Use feat: for missing coverage of a real situation.

Examples:

fix: sandbox-preflight -- blocked tool check silently no-ops when gh is missing
feat: orchestration-prompt-template -- no guidance for runner prompt when issue has no acceptance criteria

Required body content

• What the skill says -- quote or paraphrase the relevant instruction
• What actually happened or is missing -- specific description; no vague summaries
• Suggested fix or question -- propose a change or ask a clarifying question

Filing command

gh issue create \
  --repo joshrotenberg/agent-tools \
  --title "fix: <skill-name> -- <one-line description>" \
  --body "$(cat <<'EOF'
**What the skill says**

<quote or paraphrase>

**What actually happened / what is missing**

<specific description>

**Suggested fix or question**

<proposed change or question>
EOF
)"

Add relevant labels with --label to match the severity and component of the observation. Available labels: skills, agents, ci, docs, fix, feat, field-feedback, p1, p2, p3. Example: --label "skills,fix,p2" for a skill bug of moderate severity.

Check for duplicates before filing:

gh issue list --repo joshrotenberg/agent-tools --state open

One issue per observation

Don't bundle multiple unrelated findings into one issue. If you have two distinct observations, file two issues.

After filing

Continue the current task. Do not wait for the issue to be resolved. Include the issue URL in your return summary to the dispatcher or human.

Anti-patterns

• Filing mid-task for something that doesn't affect the current work (distraction)
• Vague body like "skill seems wrong" with no specific diagnosis
• Filing a duplicate without first checking gh issue list
• Filing for a preference rather than an observable divergence or gap

Related skills

• field-feedback -- for wrapper bugs, sandbox gaps, unexpected dispatch behaviors, and findings that route to repos other than joshrotenberg/agent-tools
• runner-issue-authority -- gh issue view as the authoritative source for task input
• spiral-diagnosis -- when a dispatched session is stuck (a different kind of feedback loop)