docs(agents): add skill authoring guidelines reference#327
Merged
Conversation
Canonifies lessons learned from operating and debugging inner/outer loop skills across aeo_crosslink_audit, aeo_new_guide_recommendations, improve-aeo-crosslink-skill, and improve-drafting-skills. Key patterns documented: - Silent log loss on protected branches (the main historical failure) - Explicit log write and push verification steps - Source data freshness gates and cloud agent OAuth constraints - Scope consistency checklist when expanding topic areas - Precise 'Do not' lists that don't contradict log PR requirements - Avoiding 'bi-weekly' ambiguity - Oz run URL runtime resolution (never hard-code the host) - Secrets graceful fallback pattern - Outer loop data minimum, security boundary, and draft-PR requirement - PR body integrity and repetition-loop degeneration - YAML frontmatter validation gap (style_lint.py doesn't cover .agents/) - Concrete 'Suggested skill improvement' field guidance Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR adds a new .agents/references/skill-authoring-guidelines.md reference page documenting recurring patterns for docs-repo skill authoring. The structure is useful, but a command in the new guidance does not actually validate skill frontmatter strongly enough, and a couple of statements should be tightened for accuracy.
Concerns
- The YAML frontmatter validation command can pass malformed
SKILL.mdfiles because it only checks for two---delimiters anywhere in the file. - No approved or repository spec context was provided, so there are no spec-alignment findings.
- No security-sensitive code, dependency, secret, auth, or data-handling changes were introduced.
Verdict
Found: 0 critical, 1 important, 2 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Applies the PR body integrity pattern from the new skill authoring guidelines to skills that were still using inline --body or lacked any PR body guidance: - update-changelog: replace inline --body with --body-file heredoc - sync-openapi-spec: Step 2 diff output can be long; write to file, run check_pr_body.py, then --body-file - sync_terminology: term lists can be structured and long; same pattern - sync-error-docs: Step 8 had no PR body guidance at all; adds template All four changes add the same check_pr_body.py verification step before gh pr create, consistent with improve-drafting-skills and release_updates which already follow the correct pattern. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
approved these changes
Jul 10, 2026
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
Adds
.agents/references/skill-authoring-guidelines.md— a reference doc that canonifies lessons learned from operating and debugging the docs repo's inner/outer loop skills.Skills consulted:
aeo_crosslink_audit,aeo_new_guide_recommendations,improve-aeo-crosslink-skill,improve-drafting-skills,create_pr. All patterns are grounded in real failures or fixes that occurred during development of these skills.What this documents
Inner loop skills
mainsucceed silently but write nothing). Required pattern: perpetualchore/<skill>-logbranch and explicit write/push verification.head -10after prepend,git logafter push. Do not assume file ops succeed.## Source datasection to confirm source coverage matches.oz-dev run get.Outer loop skills
## Schedule).mainbefore the outer loop reads it (state as a prerequisite).check_pr_body.pyto catch repetition-loop degeneration.General
--body-filefor all PR descriptions; runcheck_pr_body.pybefore creating or updating.style_lint.pydoes not validate.agents/skills/— use the Python frontmatter check instead.description:immediately when scope changes.Co-Authored-By: Oz oz-agent@warp.dev
Warp conversation: https://staging.warp.dev/conversation/ca30086b-6795-42e3-ba47-2df10ad19cda