docs: add generated skill rules and rewrite SKILL.md#133
docs: add generated skill rules and rewrite SKILL.md#133avivsinai merged 3 commits intoavivsinai:masterfrom
Conversation
Commit the auto-generated rules/*.md files produced by make generate-skill and remove the old hand-maintained references/commands.md. Rewrite SKILL.md to focus on agent guidance rather than command reference: - Structured "Before You Start" checklist (install, auth, context) - Platform awareness matrix (DC vs Cloud feature split) - Common workflow patterns instead of exhaustive command examples - Clear pointer to read rule files for detailed flags and usage This is PR 3 of 4 in the auto-generate skill series: 1. Add detailed docstrings to all commands (merged) 2. Generator core + make generate-skill (merged) 3. (this) Generated rules, SKILL.md rewrite, remove references/commands.md 4. Pre-commit hook + CI validation for staleness detection
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
avivsinai
left a comment
There was a problem hiding this comment.
Clean execution of the auto-generation pipeline. Test plan all green — make check-skills pass, go test ./... pass, make generate-skill + git diff skills/ shows zero drift. Spot-checked pr.md, auth.md, branch.md against CLI help — flags match exactly, platform badges correct, examples valid.
Content loss check against deleted references/commands.md: all content accounted for in the 16 generated rule files + SKILL.md env var table.
One blocking issue:
skills/bkt/SKILL.md:42 says "Bitbucket Cloud (browser-based OAuth)" — the CLI uses Atlassian API tokens, not OAuth. The --web flag opens the browser to Atlassian's token creation page (id.atlassian.com/manage-profile/security/api-tokens), not an OAuth authorization flow. Suggested replacement: Bitbucket Cloud (API token; --web opens Atlassian's token creation page).
(Bitbucket Cloud does support OAuth 2.0 for API access, and we may add it as a login option down the road, but that's not what the CLI does today — so the docs should reflect current behavior.)
This is a hand-edit in SKILL.md, not from the generator — the fix is just updating that line.
Non-blocking notes:
- SKILL.md drops the Binary/GitHub Releases install row from the old version. Minor — could add back in a follow-up.
rules/other.mdhas dual H1 headings — cosmetic inconsistency from the generator handling ungrouped commands.
- Fix incorrect "browser-based OAuth" comment — bkt uses Atlassian API tokens, not OAuth; --web opens the token creation page - Restore Binary/GitHub Releases install row in SKILL.md - Fix dual H1 headings in rules/other.md — standalone commands now use H2 within the grouped file
|
Blocking: OAuth → API token — Fixed. Updated the comment to Non-blocking 1: Missing install row — Added the Binary/GitHub Releases row back to the install table. Non-blocking 2: Dual H1 in other.md — Fixed in the generator. Standalone commands now render as H2 within All three addressed in commit 7312da5. |
Standalone commands in other.md now use properly nested headings (H2 title, H3 usage, H4 flags) instead of mixing H1/H2/H3. Adds heading depth parameter to writeFlags and writeExamples.
avivsinai
left a comment
There was a problem hiding this comment.
Blocking doc note is addressed. The Cloud auth wording now correctly refers to Atlassian API tokens and clarifies that --web opens the token creation page.
Summary
rules/*.mdfiles produced bymake generate-skillreferences/commands.mdSKILL.mdto focus on agent guidance (workflows, platform awareness, setup checklist) instead of duplicating command referenceFull Plan (4 PRs)
cmd/docgen/+internal/docgen/) +make generate-skillSKILL.md Changes
Generated Rule Files (16 total)
Each file covers one command group with subcommand tables, flags, platform badges, and examples:
admin.md,auth.md,branch.md,commit.md,context.md,extension.md,issue.md,other.md,perms.md,pipeline.md,pr.md,project.md,repo.md,status.md,variable.md,webhook.mdTest plan
make check-skills— symlinks validmake generate-skill— regenerating produces identical outputgo test ./...passes