fix(skill): allow missing descriptions

[Astro-Han]

Summary

Allow skill frontmatter to omit description while still loading the skill, and keep description-less skills out of automatic skill prompt listings.

Why

This absorbs the still-relevant part of upstream opencode stability follow-up anomalyco/opencode#26391 for #512. Before this change, PawWork skipped otherwise valid skills when the skill only had a name; after this change, those skills remain available for direct loading without being advertised as auto-matchable skills.

Related Issue

Closes #512 for the anomalyco/opencode#26391 slice only. Other #512 candidates were checked separately: deterministic tool ordering, npm shim signal forwarding, and shell carriage-return normalization are already covered locally; the network-options AppRuntime follow-up remains a separate possible slice.

Human Review Status

Pending. A human should make the final merge decision after reviewing the final diff and verification evidence.

Review Focus

Please check that the behavior boundary is right: description-less skills should load through the skill registry/API, but should not appear in formatted automatic skill prompt lists.

Risk Notes

Low. This changes skill metadata shape from required to optional and updates the generated SDK response type. It does not touch UI, desktop packaging, runtime process behavior, or onboarding.

How To Verify

Focused tests: bun --cwd packages/opencode test test/skill/skill.test.ts test/session/system.test.ts -> 23 pass, 0 fail
Opencode typecheck: bun --cwd packages/opencode typecheck -> passed
SDK typecheck: bun --cwd packages/sdk/js typecheck -> passed
Diff check: git diff --check -> passed

Screenshots or Recordings

N/A. No visible UI changes.

Checklist

• Human review status is stated above as pending, approved, or not required
• I linked the related issue, or stated why there is no issue
• This PR has type, primary area, and priority labels, or I requested maintainer labeling
• I described the review focus and any meaningful risks
• I listed the relevant verification steps and the key result for each
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope
• I manually checked visible UI or copy changes when needed, with screenshots or recordings
• I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes
• I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant
• I reviewed the final diff for unrelated changes and suspicious dependency changes
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English

Summary by CodeRabbit

• Changes
  • Skill descriptions are now optional in the system, though skills without descriptions remain hidden from visibility
  • Skills without descriptions are filtered from formatted prompt output, keeping generated prompts focused on well-defined entries
  • "No skills available" message displays when the skill list contains no skills with descriptions
  • Enhanced filtering ensures improved skill visibility handling in generated prompts

[coderabbitai]

Warning

Rate limit exceeded

@Astro-Han has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 10 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 91154a01-2a3a-4917-86c8-a771e3b0589b

📥 Commits

Reviewing files that changed from the base of the PR and between f5ebcce and aefec21.

📒 Files selected for processing (3)

• packages/opencode/src/skill/index.ts
• packages/opencode/src/tool/registry.ts
• packages/opencode/test/tool/skill.test.ts

📝 Walkthrough

Walkthrough

The Skill.Info schema now treats description as optional, and the fmt formatter filters out skills without descriptions from all output, returning "No skills…" when none remain after filtering. Tests verify the new behavior across discovery and formatting paths.

Changes

Optional skill description filtering

Layer / File(s)	Summary
Schema update and formatter filtering packages/opencode/src/skill/index.ts	Skill.Info marks description as optional. The fmt function filters skills to only those with defined descriptions, returns "No skills…" when none match, and applies the filtered set to both verbose and non-verbose output paths.
Test coverage for optional descriptions and filtering packages/opencode/test/session/system.test.ts, packages/opencode/test/skill/skill.test.ts	System and skill tests validate that skills without descriptions are discovered but filtered from formatted prompts in both verbose and non-verbose modes, and that "No skills are currently available" is returned when no descriptions exist.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

P3

Poem

🐰 A skill without words now finds its place,
Optional descriptions set the pace,
Filtered from prompts with grace and care,
Silent skills vanish into air! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(skill): allow missing descriptions' is concise, follows Conventional Commits format, and clearly describes the main change: making skill descriptions optional.
Description check	✅ Passed	The PR description is comprehensive and follows the template structure with all major sections completed, including summary, rationale, issue linking, review focus, risks, and verification steps.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/i512-skill-description

---

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 and usage tips.}

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

[gemini-code-assist]

Code Review

This pull request makes the description field optional for skills and ensures that skills without descriptions are excluded from formatted output. Key changes include updating the Zod schema and generated TypeScript types, modifying the fmt function to filter out undescribed skills, and adding comprehensive tests to verify this behavior. I have no feedback to provide.

[Astro-Han]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.