---
id: 10496
title: Add skill trigger pre-flight for prompts and A2A
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
assignees:
  - neo-gpt
createdAt: '2026-04-29T14:52:45Z'
updatedAt: '2026-04-29T15:56:01Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10496'
author: neo-gpt
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-29T15:56:01Z'
---
# Add skill trigger pre-flight for prompts and A2A

## Context

@tobiu surfaced a recurring swarm failure: Gemini-family sessions can forget to invoke applicable skills when the request uses ordinary action words instead of explicit skill names. Examples include `test` needing disambiguation between `unit-test` and `whitebox-e2e`, and `review` needing disambiguation toward `pr-review` when the target is a PR/diff/approval cycle.

This ticket follows the existing per-turn memory pattern in `AGENTS.md §21`: skill awareness belongs in turn-loaded memory when missing the trigger causes silent protocol failure.

## The Problem

The current workflow skill table correctly documents lifecycle skill triggers, but it assumes the agent notices that a prompt maps to a skill. In practice, prompts and A2A messages often arrive as natural-language tasks:

- "test this"
- "review this PR"
- "re-review after my fix"
- "finalize/open the PR"
- "pick up this ticket"

When the agent misses that semantic mapping, the failure happens before the skill body is ever loaded. That is especially visible in A2A contexts, where a mailbox message may be treated as coordination metadata rather than as a prompt requiring the same trigger discipline as a direct user request.

This is not a lack of skill content. It is a trigger-reflex gap.

## The Architectural Reality

- `AGENTS.md:485` begins `§21. Workflow Skills (when to invoke)`, the current per-turn awareness table.
- `AGENTS.md:487` says skills must be invoked before the trigger action and that the table exists so the trigger -> skill loop fires reliably even when context pruning evicts skill files.
- `AGENTS.md:502` explicitly documents the empirical failure mode: skipped skill invocation causes gate/protocol/template failures silently.
- `AGENTS.md:504` currently says tactical/domain skills such as `unit-test` and `whitebox-e2e` remain discoverable via directory listing rather than per-turn awareness.
- `AGENTS_STARTUP.md:61` already requires listing `.agents/skills/` and reading relevant `SKILL.md` before multi-step testing/debugging/scaffolding, but this is boot/startup discipline, not a per-prompt or A2A-message pre-flight.
- Prior related issue #10365 established the compact workflow-skills table. This ticket narrows to the next missing layer: semantic trigger detection before prompt/A2A handling.

Five-stage challenge chain result:

1. **Premise:** Real and observed in current swarm coordination; the issue is skill under-triggering, not missing skill bodies.
2. **Prescription:** Add a compact AGENTS.md pre-flight. Do not create a new skill; the problem is detecting existing skill applicability.
3. **Substrate:** `AGENTS.md` per-turn memory owns this discipline because it must fire before planning and before opening any specific skill.
4. **Consumer:** Agent harnesses and A2A mailbox readers. The output must be terse, router-like, and survive context pruning.
5. **Service Boundary:** No MCP, Memory Core, or skill payload changes are required for v1.

## The Fix

Add a compact "Skill Trigger Pre-Flight" near `AGENTS.md §21`, before the mailbox/turn-start sections. The rule should require every agent, before acting on a user prompt or A2A message, to identify the action and target object, then compare that pair against known skill triggers.

The pre-flight should explicitly cover ambiguous words by object:

- `review` + PR/diff/approval/LGTM/re-review => `pr-review`
- `test` + unit/spec/Playwright unit/file.spec => `unit-test`
- `test` + E2E/end-to-end/user flow/whitebox/Neural Link => `whitebox-e2e`
- assigned issue / ticket pickup => `ticket-intake`
- commit / push / open PR / finalize branch => `pull-request`
- regression / "used to work" / prior decision context => `memory-mining`

The wording should say "check prompt intent against skill triggers", not "check skill names", because users and agents usually do not name the skill explicitly.

## Acceptance Criteria

- [ ] `AGENTS.md §21` gains a compact Skill Trigger Pre-Flight applying to every user prompt and every A2A message.
- [ ] The pre-flight requires action + target-object disambiguation, not raw keyword matching.
- [ ] The pre-flight includes explicit examples for `review`, `test`, ticket pickup, PR finalization, and regression/history prompts.
- [ ] The text preserves Progressive Disclosure: it routes to existing `SKILL.md` files but does not inline heavy skill payloads.
- [ ] The text avoids implying that tactical skills should always be loaded; it only requires loading them when the semantic trigger matches.
- [ ] A short note clarifies that A2A mailbox messages count as prompts for skill-trigger purposes.
- [ ] `git diff --check` passes.

## Out of Scope

- Creating a new skill.
- Editing `.agents/skills/*` payloads.
- Building an automated skill-trigger evaluation harness. Discussion `#10320` covers broader skill trigger eval infrastructure.
- Changing MCP tool behavior or Memory Core mailbox semantics.
- Refactoring the full workflow skills table.

## Avoided Traps / Gold Standards Rejected

- **Naive keyword routing:** Rejected. `review` can mean conceptual review, PR review, or design critique; `test` can mean A2A smoke test, unit test, or E2E test. The trigger must use action plus target object.
- **New skill for skill-triggering:** Rejected. The failure happens before skill selection; a new skill would itself need to be triggered and therefore would not solve the base problem.
- **Inlining full tactical skill rules into AGENTS.md:** Rejected. That breaks Progressive Disclosure and bloats turn memory. AGENTS.md should only contain the router/pre-flight.
- **Treating A2A as lower priority:** Rejected. A2A messages can assign reviews, request re-reviews, or hand off ticket work, so they must pass through the same skill trigger gate as user prompts.

## Related

- #10365 — introduced the compact per-turn workflow skills table.
- #10376 — tightened A2A commentId hand-off reflexes for PR review / PR author workflows.
- Discussion #10320 — broader skill trigger evaluation infrastructure, deliberately out of scope for this small AGENTS.md router change.
- Current Memory Core session captured the analysis and recommendation.

Origin Session ID: ea6898ba-531f-4162-996b-99e7b235c120

Retrieval Hint: "skill trigger pre-flight prompts A2A review test unit-test whitebox-e2e pr-review AGENTS.md §21 Gemini under-triggering"

## Timeline

- 2026-04-29T14:52:47Z @neo-gpt added the `documentation` label
- 2026-04-29T14:52:47Z @neo-gpt added the `enhancement` label
- 2026-04-29T14:52:47Z @neo-gpt added the `ai` label
- 2026-04-29T14:52:48Z @neo-gpt added the `architecture` label
- 2026-04-29T14:54:12Z @neo-gpt assigned to @neo-gpt
- 2026-04-29T14:56:33Z @neo-gpt referenced in commit `2d9aab0` - "feat(agents): add skill trigger pre-flight (#10496)"
- 2026-04-29T14:57:29Z @neo-gpt cross-referenced by PR #10497
- 2026-04-29T15:00:38Z @neo-gpt referenced in commit `5af8f4f` - "feat(agents): add skill trigger pre-flight (#10496)"
- 2026-04-29T15:13:09Z @neo-gpt referenced in commit `5e69b99` - "feat(agents): add skill trigger pre-flight (#10496)"
- 2026-04-29T15:19:07Z @neo-gpt referenced in commit `077f0c8` - "feat(agents): add skill trigger pre-flight (#10496)"
- 2026-04-29T15:28:28Z @neo-gpt referenced in commit `0bf63a3` - "feat(agents): add skill trigger pre-flight (#10496)"
- 2026-04-29T15:56:02Z @tobiu closed this issue
- 2026-04-29T15:56:02Z @tobiu referenced in commit `9cd804c` - "feat(agents): add skill trigger pre-flight (#10496) (#10497)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-29T22:51:12Z @neo-gpt cross-referenced by #10513
- 2026-04-30T09:56:33Z @neo-gpt cross-referenced by #10523

