docs(#28): codify extension point annotation convention in skill resolution section - #30
docs(#28): codify extension point annotation convention in skill resolution section#30fullsend-ai-coder[bot] wants to merge 2 commits into
Conversation
…lution section Add the inline YAML comment convention for extension point skills to AGENTS.md section 7 (Skill resolution). When a skill declared in agent frontmatter is intentionally absent from this repo and expected to be provided by target repos or org-level configuration, the reference should be annotated with an `# extension point:` comment. This makes the intent discoverable at the point of contact without requiring readers to consult the skill resolution docs. The convention matches the existing annotation on the customer-research skill in agents/prioritize.md line 5 and prevents the false-positive review cycle seen in the PR #12 to #21 saga. Closes #28
PR Summary by QodoDocument extension-point skill annotation convention in AGENTS.md
AI Description
High-Level Assessment
Files changed (1)
|
|
/fs-fix this feels like too much new context for AGENTS.md. Can this go somewhere deeper in the repo a la progressive context discovery? |
Code Review by Qodo
Context used✅ Compliance rules (platform):
55 rules 1. AGENTS.md protected file modified
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| When declaring an extension point skill in agent frontmatter — a skill | ||
| that is intentionally absent from this repo and expected to be provided | ||
| by target repos or org-level configuration — annotate the reference with | ||
| an inline YAML comment: | ||
|
|
||
| skills: | ||
| - customer-research # extension point: provided by target repos | ||
|
|
||
| This annotation gives agents and human readers immediate context at the | ||
| point of contact, without needing to consult this section. |
There was a problem hiding this comment.
1. agents.md protected file modified 📜 Skill insight § Compliance
This PR modifies AGENTS.md, which is a protected governance/infrastructure path and must not be auto-approved. Ensure the change receives explicit human review/approval (e.g., CODEOWNERS/maintainers) even if the modification is documentation-only.
|
🤖 Fix · ❌ Terminated · Started 7:02 PM UTC · Ended 7:09 PM UTC |
|
🤖 Finished Retro · ✅ Success · Started 7:03 PM UTC · Completed 7:11 PM UTC |
Move extension point annotation guidance from AGENTS.md section 7 to docs/skill-resolution.md for progressive context discovery. AGENTS.md now contains a brief pointer to the deeper document. Addresses review feedback on #30
|
🤖 Finished Fix · ✅ Success · Started 7:02 PM UTC · Completed 7:09 PM UTC |
|
PR #30 adds 11 lines to AGENTS.md documenting the extension point annotation convention. The human maintainer (ralphbean) rejected the placement, commenting that it feels like too much new context for AGENTS.md and asking for progressive context discovery. This is the 5th retro-filed issue (#13, #17, #18, #20, #28) on the same topic (extension point skills) consuming significant agent compute over 4 days for what amounts to a 1-line YAML comment plus general docs. The code agent implemented the issue correctly; the problem is upstream in the retro agent's proposal, which prescribed AGENTS.md as the target without applying the progressive disclosure principle from its own loaded agent-scaffolding skill. Two proposals target the retro agent's decision-making in fullsend-ai/fullsend. Proposals filed
|
|
I'm just going to drop this. That docs/skill-resolution.md change looks so clunky. |
|
🤖 Finished Retro · ✅ Success · Started 8:33 PM UTC · Completed 8:42 PM UTC |
|
PR #30 in fullsend-ai/agents was a docs-only PR adding the extension point annotation convention to AGENTS.md. The human maintainer (ralphbean) asked the fix agent to move the content to a deeper location via Proposals filed
|
1 participant
Add the inline YAML comment convention for extension point skills to AGENTS.md section 7 (Skill resolution). When a skill declared in agent frontmatter is intentionally absent from this repo and expected to be provided by target repos or org-level configuration, the reference should be annotated with an
# extension point:comment. This makes the intent discoverable at the point of contact without requiring readers to consult the skill resolution docs.The convention matches the existing annotation on the customer-research skill in agents/prioritize.md line 5 and prevents the false-positive review cycle seen in the PR #12 to #21 saga.
Closes #28
Post-script verification
agent/28-extension-point-docs)c362e3f6eeb2e78490e58745e4daf652f2abc402..HEAD)