---
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