docs: align SKILL.md with agentskills.io best practices#3
Merged
Conversation
- Fix description to third-person, trigger-only format - Extract smithers-worker agent to references/ (progressive disclosure) - Add Progress Checklist for tracking workflow state - Add Configuration table with rationale for magic numbers - Remove redundant commentary Reduces SKILL.md from 375 to 297 lines while improving discoverability and compliance with repo best-practices doc. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Resolve conflicts while preserving best-practices compliance: - Keep third-person, trigger-only description - Keep progressive disclosure (external worker file) - Keep Progress Checklist and Configuration sections - Update terminology from "beads" to generic "tasks" Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Merge poll + check into single poll_check node to comply with beads-skills best practices (≤8 nodes for DOT diagrams). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Integrate the Ralph loop pattern (iterative refinement driven by backpressure) into smithers-worker specification: - Add Ralph loop pattern description and principles - Define stop hooks (tests, lints, builds, types) as quality gates - Introduce completion promise concept - Document iterative stop-hook behavior - Update workflow to show Ralph loop phases - Add architecture comparison (Smithers vs Ralph) - Include references to Ralph pattern resources Workers now iterate until all stop hooks pass before committing, ensuring completion promise is fulfilled. Smithers orchestrates multiple parallel Ralph loops with review-based gating. Refs: https://ghuntley.com/ralph/ Refs: https://github.com/ghuntley/how-to-ralph-wiggum Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This reverts commit f59dc08.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Align SKILL.md with agentskills.io spec and integrate the Ralph loop pattern into smithers-worker.
Changes
Frontmatter & Description
name+descriptiononly (per spec)Progressive Disclosure
references/smithers-worker.mdRalph Loop Integration 🆕
New Sections
## Progress Checklistfor tracking workflow state## Configurationtable with rationale for magic numbers## See Alsosection with Ralph pattern referencesCompliance Fixes
Architecture: Smithers vs Ralph
Smithers workers internally use Ralph loop discipline (iterate until stop hooks pass), while Smithers orchestrates multiple Ralph loops in parallel with review-based gating.
References
Test plan
nameanddescriptionkeys## Quick Referenceand## Failure Modespresentreferences/smithers-worker.mdexists and includes Ralph loop pattern🤖 Generated with Claude Code