orbstack-best-practices
Patterns for OrbStack Linux VMs and Docker on macOS. Covers orbctl/orb commands, machine lifecycle, cloud-init, networking, file sharing, and SSH access. Must use when working with OrbStack, orbctl commands, or Linux VMs on macOS.
93
89%
Does it follow best practices?
Impact
99%
2.10xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly identifies its niche (OrbStack on macOS), lists specific capabilities, and includes an explicit 'Must use when' trigger clause. The trigger terms are natural and specific enough to avoid conflicts with generic Docker or VM management skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and domains: orbctl/orb commands, machine lifecycle, cloud-init, networking, file sharing, and SSH access. These are concrete, identifiable capabilities. | 3 / 3 |
Completeness | Clearly answers both 'what' (patterns for OrbStack Linux VMs and Docker, covering orbctl commands, machine lifecycle, cloud-init, networking, file sharing, SSH) and 'when' ('Must use when working with OrbStack, orbctl commands, or Linux VMs on macOS'). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'OrbStack', 'orbctl', 'orb commands', 'Linux VMs', 'macOS', 'Docker', 'cloud-init', 'SSH access'. Good coverage of terms a user working with OrbStack would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: OrbStack on macOS. The specific tool names (OrbStack, orbctl, orb) and the macOS + Linux VM context make it very unlikely to conflict with other skills like generic Docker or SSH skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality reference skill that excels in conciseness and actionability, providing comprehensive, copy-paste ready commands for OrbStack usage. Its main weaknesses are the lack of explicit validation checkpoints in multi-step workflows and the monolithic structure that could benefit from splitting detailed sections into separate reference files. The content is well-organized within the single file but would better serve as an overview with pointers to detailed sub-documents.
Suggestions
Add explicit validation/verification steps to multi-step workflows, especially for cloud-init provisioning (e.g., 'create → check status → verify packages installed → troubleshoot if needed') and Docker configuration changes.
Split detailed sections (Docker Integration, Kubernetes, Cloud-Init, Networking) into separate reference files and keep SKILL.md as a concise overview with links, improving progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient throughout. It avoids explaining what OrbStack is beyond a single introductory sentence, uses tables for reference data, and relies on concrete commands rather than prose explanations. Every section earns its place with minimal filler. | 3 / 3 |
Actionability | Nearly every section provides copy-paste ready commands and concrete examples. Cloud-init includes a complete YAML example, SSH shows exact connection strings, Docker integration covers specific use cases with executable commands, and troubleshooting gives specific remediation steps. | 3 / 3 |
Workflow Clarity | While individual commands and sections are clear, multi-step workflows lack explicit validation checkpoints. For example, the cloud-init section shows creation and debugging separately but doesn't present a clear 'create → validate → fix → retry' loop. The machine lifecycle is presented as independent commands rather than a sequenced workflow with verification steps. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers and logical grouping, but it's a monolithic document (~250 lines) with no references to external files. Some sections like Docker Integration, Kubernetes, and Networking could be split into separate reference files to keep the main skill leaner as an overview. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- NeverSight/skills_feed
- Commit
aa009ea
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.