Skip to content

docs: sharpen agent skill guidance#578

Closed
miguel-heygen wants to merge 1 commit intomainfrom
docs/sharpen-agents-guidance
Closed

docs: sharpen agent skill guidance#578
miguel-heygen wants to merge 1 commit intomainfrom
docs/sharpen-agents-guidance

Conversation

@miguel-heygen
Copy link
Copy Markdown
Collaborator

Problem

The generated project AGENTS.md described HyperFrames skills as useful context, but it was softer than the generated CLAUDE.md guidance. Agents could read it as optional advice instead of a required precondition for composition work.

What this fixes

  • Sharpens the root AGENTS.md skills section with a direct requirement to invoke relevant HyperFrames skills before composition edits.
  • Sharpens the generated project AGENTS.md template with the same prescriptive line.
  • Adds an explicit missing-skills fallback: stop and ask the user to install/run the HyperFrames skills setup before composition work continues.
  • Leaves generated CLAUDE.md unchanged because it already carries the stricter wording.

Root cause

The generated CLAUDE.md had been upgraded to “use these first” language, while AGENTS.md still used descriptive wording. That created inconsistent guidance between agent config surfaces even though both files are copied by hyperframes init.

Verification

Local checks

  • bunx oxfmt --check AGENTS.md packages/cli/src/templates/_shared/AGENTS.md
  • git diff --check
  • Lefthook pre-commit: format
  • Lefthook commit-msg: commitlint

Generated-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-skills
  • rg -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.md

Browser verification

  • Not applicable: this is agent guidance text only and has no browser-exercisable flow.

Notes

  • This PR intentionally touches only AGENTS.md surfaces. CLAUDE.md already had the stronger prescriptive guidance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant