fix: make worker documentation entrypoint optional

[ytallo]

Summary

• make the canonical skills/SKILL.md entrypoint optional for every worker
• publish nested markdown documents even when the canonical entrypoint is absent
• remove the bootstrap-only PR gate and align tests and documentation with the optional contract

Root cause

The registry payload builder rejected any worker that had markdown under skills/ without a root skills/SKILL.md. The console release contains skills/design-console-ui/SKILL.md but no root entrypoint, so the release failed after the worker package had already been published.

Impact

Future releases can publish nested worker documentation independently. Workers that still provide skills/SKILL.md retain the existing registry key mapping, and releases with no non-empty markdown continue to skip the documentation upload.

Validation

• python3 .github/scripts/test_build_skills_payload.py — 4 passed
• python3 -m pytest .github/scripts/tests -q — 195 passed, 3 subtests passed
• reproduced the console 1.9.6 payload build with only skills/design-console-ui/SKILL.md
• python3 -m py_compile for the modified Python files
• git diff --check

Summary by CodeRabbit

• New Features

  • Skill documentation is now optional for workers.
  • Additional non-empty Markdown files under a worker’s skills directory can be published without requiring a SKILL.md overview.
  • Optional skill overviews continue to be supported when provided.

• Documentation

  • Updated authoring, validation, publishing, and new-worker guidance to reflect the optional documentation workflow.

• Bug Fixes

  • Workers without SKILL.md can now pass validation when otherwise valid.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview	Aug 17, 2026 9:49pm
workers-tech-spec	Ready	Preview	Aug 17, 2026 9:49pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 06959e35-1fe0-4e74-8bb0-3c00227066ff

📥 Commits

Reviewing files that changed from the base of the PR and between b2ebb29 and 0d647b9.

📒 Files selected for processing (8)

• .github/scripts/build_skills_payload.py
• .github/scripts/test_build_skills_payload.py
• .github/scripts/tests/test_validate_worker.py
• .github/scripts/validate_worker.py
• DOCUMENTATION_GUIDELINES.md
• docs/architecture/skills-and-permissions.md
• docs/architecture/testing-and-ci.md
• docs/sops/new-worker.md

---

📝 Walkthrough

Walkthrough

The PR makes skills/SKILL.md optional. Payload generation collects other non-empty Markdown files, worker validation removes the requirement, and documentation reflects the updated lifecycle.

Changes

Optional skill documentation

Layer / File(s)	Summary
Collect skill documents .github/scripts/build_skills_payload.py, .github/scripts/test_build_skills_payload.py	collect_skills accepts nested Markdown documents without skills/SKILL.md. Tests verify the resulting payload.
Remove skill validation gate .github/scripts/validate_worker.py, .github/scripts/tests/test_validate_worker.py	Worker validation removes bootstrap skill requirements and accepts workers without SKILL.md.
Update skill documentation guidance DOCUMENTATION_GUIDELINES.md, docs/architecture/..., docs/sops/new-worker.md	Documentation describes optional skill overviews and publishing of additional non-empty Markdown files under skills/.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• iii-hq/workers#558: Both changes update skill-documentation handling and Markdown collection.
• iii-hq/workers#575: Both changes modify skills/SKILL.md handling.
• iii-hq/workers#659: This change supports publishing standalone worker skill documents without SKILL.md.

Suggested reviewers: sergiofilhowz

Poem

A rabbit found Markdown deep in the tree,
No SKILL.md gate could stop it, you see.
The payload grew wide,
Validation complied,
And docs hopped along happily.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/remove-skill-validation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

skill-check — worker

0 verified, 61 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.