docs: sharpen agent skill guidance#578
Closed
miguel-heygen wants to merge 1 commit intomainfrom
Closed
Conversation
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
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.
Problem
The generated project
AGENTS.mddescribed HyperFrames skills as useful context, but it was softer than the generatedCLAUDE.mdguidance. Agents could read it as optional advice instead of a required precondition for composition work.What this fixes
AGENTS.mdskills section with a direct requirement to invoke relevant HyperFrames skills before composition edits.AGENTS.mdtemplate with the same prescriptive line.CLAUDE.mdunchanged because it already carries the stricter wording.Root cause
The generated
CLAUDE.mdhad been upgraded to “use these first” language, whileAGENTS.mdstill used descriptive wording. That created inconsistent guidance between agent config surfaces even though both files are copied byhyperframes init.Verification
Local checks
bunx oxfmt --check AGENTS.md packages/cli/src/templates/_shared/AGENTS.mdgit diff --checkGenerated-project smoke at
/tmp/hf-agents-guidance-proof:bun packages/cli/src/cli.ts init /tmp/hf-agents-guidance-proof --example blank --non-interactive --skip-skillsrg -n "Always invoke|Skills not available|npx hyperframes skills|npx skills add" /tmp/hf-agents-guidance-proof/AGENTS.md AGENTS.md packages/cli/src/templates/_shared/AGENTS.mdBrowser verification
Notes
AGENTS.mdsurfaces.CLAUDE.mdalready had the stronger prescriptive guidance.