72d4b0dfd2
Beta skills now use disable-model-invocation: true to prevent accidental auto-triggering. Descriptions written as future stable descriptions with [BETA] prefix for clean promotion. Updated solutions doc and AGENTS.md promotion checklist to include removing the field.
88 lines
4.6 KiB
Markdown
88 lines
4.6 KiB
Markdown
---
|
|
title: "Beta skills framework: parallel skills with -beta suffix for safe rollouts"
|
|
category: skill-design
|
|
date: 2026-03-17
|
|
module: plugins/compound-engineering/skills
|
|
component: SKILL.md
|
|
tags:
|
|
- skill-design
|
|
- beta-testing
|
|
- skill-versioning
|
|
- rollout-safety
|
|
severity: medium
|
|
description: "Pattern for trialing new skill versions alongside stable ones using a -beta suffix. Covers naming, plan file naming, internal references, and promotion path."
|
|
related:
|
|
- docs/brainstorms/2026-03-17-beta-skills-framework-brainstorm.md
|
|
- docs/solutions/skill-design/compound-refresh-skill-improvements.md
|
|
---
|
|
|
|
## Problem
|
|
|
|
Core workflow skills like `ce:plan` and `deepen-plan` are deeply chained (`ce:brainstorm` → `ce:plan` → `deepen-plan` → `ce:work`) and orchestrated by `lfg` and `slfg`. Rewriting these skills risks breaking the entire workflow for all users simultaneously. There was no mechanism to let users trial new skill versions alongside stable ones.
|
|
|
|
Alternatives considered and rejected:
|
|
- **Beta gate in SKILL.md** with config-driven routing (`beta: true` in `compound-engineering.local.md`): relies on prompt-level conditional routing which risks instruction blending, requires setup integration, and adds complexity to the skill files themselves.
|
|
- **Pure router SKILL.md** with both versions in `references/`: adds file-read penalty and refactors stable skills unnecessarily.
|
|
- **Separate beta plugin**: heavy infrastructure for a temporary need.
|
|
|
|
## Solution
|
|
|
|
### Parallel skills with `-beta` suffix
|
|
|
|
Create separate skill directories alongside the stable ones. Each beta skill is a fully independent copy with its own frontmatter, instructions, and internal references.
|
|
|
|
```
|
|
skills/
|
|
├── ce-plan/SKILL.md # Stable (unchanged)
|
|
├── ce-plan-beta/SKILL.md # New version
|
|
├── deepen-plan/SKILL.md # Stable (unchanged)
|
|
└── deepen-plan-beta/SKILL.md # New version
|
|
```
|
|
|
|
### Naming and frontmatter conventions
|
|
|
|
- **Directory**: `<skill-name>-beta/`
|
|
- **Frontmatter name**: `<skill:name>-beta` (e.g., `ce:plan-beta`)
|
|
- **Description**: Write the intended stable description, then prefix with `[BETA]`. This ensures promotion is a simple prefix removal rather than a rewrite.
|
|
- **`disable-model-invocation: true`**: Prevents the model from auto-triggering the beta skill. Users invoke it manually with the slash command. Remove this field when promoting to stable.
|
|
- **Plan files**: Use `-beta-plan.md` suffix (e.g., `2026-03-17-001-feat-auth-flow-beta-plan.md`) to avoid clobbering stable plan files
|
|
|
|
### Internal references
|
|
|
|
Beta skills must reference each other by their beta names:
|
|
- `ce:plan-beta` references `/deepen-plan-beta` (not `/deepen-plan`)
|
|
- `deepen-plan-beta` references `ce:plan-beta` (not `ce:plan`)
|
|
|
|
### What doesn't change
|
|
|
|
- Stable `ce:plan` and `deepen-plan` are completely untouched
|
|
- `lfg`/`slfg` orchestration continues to use stable skills — no modification needed
|
|
- `ce:brainstorm` still hands off to stable `ce:plan` — no modification needed
|
|
- `ce:work` consumes plan files from either version (reads the file, doesn't care which skill wrote it)
|
|
|
|
### Tradeoffs
|
|
|
|
**Simplicity over seamless integration.** Beta skills exist as standalone, manually-invoked skills. They won't be auto-triggered by `ce:brainstorm` handoffs or `lfg`/`slfg` orchestration without further surgery to those skills, which isn't worth the complexity for a trial period.
|
|
|
|
**Intended usage pattern:** A user can run `/ce:plan` for the stable output, then run `/ce:plan-beta` on the same input to compare the two plan documents side by side. The `-beta-plan.md` suffix ensures both outputs coexist in `docs/plans/` without collision.
|
|
|
|
## Promotion path
|
|
|
|
When the beta version is validated:
|
|
|
|
1. Replace stable `SKILL.md` content with beta skill content
|
|
2. Restore stable frontmatter: remove `[BETA]` prefix from description, restore stable `name:`
|
|
3. Remove `disable-model-invocation: true` so the model can auto-trigger it
|
|
4. Update all internal references back to stable names
|
|
5. Restore stable plan file naming (remove `-beta` from the convention)
|
|
6. Delete the beta skill directory
|
|
7. Update README.md: remove from Beta Skills section, verify counts
|
|
8. Verify `lfg`/`slfg` work with the promoted skill
|
|
9. Verify `ce:work` consumes plans from the promoted skill
|
|
|
|
## Prevention
|
|
|
|
- When adding a beta skill, always use the `-beta` suffix consistently in directory name, frontmatter name, description, plan file naming, and all internal skill-to-skill references
|
|
- Always test that stable skills are completely unaffected by the beta skill's existence
|
|
- Keep beta and stable plan file suffixes distinct so outputs can coexist for comparison
|