4.2 KiB
title, category, date, module, component, tags, severity, description, related
| title | category | date | module | component | tags | severity | description | related | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Beta skills framework: parallel skills with -beta suffix for safe rollouts | skill-design | 2026-03-17 | plugins/compound-engineering/skills | SKILL.md |
|
medium | Pattern for trialing new skill versions alongside stable ones using a -beta suffix. Covers naming, plan file naming, internal references, and promotion path. |
|
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: trueincompound-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 conventions
- Directory:
<skill-name>-beta/ - Frontmatter name:
<skill:name>-beta(e.g.,ce:plan-beta) - Description prefix:
[BETA]to make it visually obvious - Plan files: Use
-beta-plan.mdsuffix (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-betareferences/deepen-plan-beta(not/deepen-plan)deepen-plan-betareferencesce:plan-beta(notce:plan)
What doesn't change
- Stable
ce:plananddeepen-planare completely untouched lfg/slfgorchestration continues to use stable skills — no modification neededce:brainstormstill hands off to stablece:plan— no modification neededce:workconsumes 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:
- Replace stable
SKILL.mdcontent with beta skill content - Restore stable frontmatter: remove
[BETA]prefix, restore stablename: - Update all internal references back to stable names
- Restore stable plan file naming (remove
-betafrom the convention) - Delete the beta skill directory
- Update README.md: remove from Beta Skills section, verify counts
- Verify
lfg/slfgwork with the promoted skill - Verify
ce:workconsumes plans from the promoted skill
Prevention
- When adding a beta skill, always use the
-betasuffix 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