Brainforge Knowledge

skill-consolidator

4 min read

Skill consolidator

Automated system that scans standalone Cursor skills and proposes (or applies) merges into mode-driven orchestrators. Runs weekly via GitHub Actions and on demand through the skill-consolidator Cursor skill.

What it does

The consolidator enumerates first-party skills under .cursor/skills/ whose frontmatter has consolidation-review: pending (or is missing the field entirely). For each candidate it:

  1. Classifies the skill by asking Azure OpenAI (gpt-5-mini on brainforge-openai-eastus2) whether it should merge into an existing orchestrator, cluster with siblings into a potential new orchestrator, or stay standalone.
  2. Routing-checks merge proposals — a second LLM call feeds the candidate’s description through the target orchestrator’s mode-resolution rules to confirm the proposed mode would actually be selected. If the router picks a different mode, the proposal is downgraded to report-only instead of being applied.
  3. Applies verified merges:
    • Appends a ## Mode: <name> section to the target orchestrator’s SKILL.md containing the candidate’s body verbatim (heading levels demoted by one, no LLM rewording).
    • Adds a single sentence to the orchestrator’s frontmatter description noting the new mode.
    • Creates an entry in scripts/skill-shims.manifest.json mapping the old skill name → orchestrator + mode.
    • Regenerates thin-alias shims by running scripts/generate-skill-shims.mjs.
  4. Writes an audit report to knowledge/engineering/cursor-skills/audits/YYYY-MM-DD-skill-consolidation.md.

The consolidator never modifies existing orchestrator mode bodies, auto-merges PRs, or rewrites skill text. The only LLM-generated text is a single sentence in the orchestrator description.

When it runs

TriggerCadenceHow
Scheduled cronEvery Monday, 13:00 UTC (~9am ET).github/workflows/skill-consolidation.yml
Manual dispatchOn demandGitHub Actions tab → “Weekly skill consolidation” → “Run workflow” (with optional dry_run input)
Local runOn demandnode .github/scripts/propose-skill-consolidations.js or via the skill-consolidator Cursor skill

Frontmatter convention

Skills are eligible for consolidation when their frontmatter consolidation-review field is:

ValueMeaning
(missing)Default-pending — new skills without the field are candidates
pendingExplicitly queued for the next consolidation pass
ignoreOpted out — the consolidator skips these entirely
consolidatedAlready merged — set on thin-alias shims after consolidation

To protect a skill from consolidation, add to its frontmatter:

consolidation-review: ignore

The --bootstrap flag was used once to stamp ignore on all 56 preexisting non-orchestrator skills, ensuring the cron doesn’t touch them until a human changes the tag to pending.

How to use it locally

Prerequisites

You need Azure OpenAI credentials in your shell environment:

export AZURE_OPENAI_API_KEY=<brainforge-openai-eastus2 key>
export AZURE_OPENAI_CHAT_BASE_URL=https://brainforge-openai-eastus2.openai.azure.com
# Optional — defaults to gpt-5-mini if unset
export AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-5-mini

Get the key from 1Password (item: brainforge-openai-eastus2) or apps/platform/.env.local.

Dry run (no writes)

Prints proposals to stdout without modifying any files:

node .github/scripts/propose-skill-consolidations.js --dry-run

Full run (applies changes locally)

Applies merges, updates the manifest, regenerates shims, and writes an audit report:

node .github/scripts/propose-skill-consolidations.js

After a full run, open a PR for review:

git checkout -b skill-consolidation/manual-$(date +%Y-%m-%d)
git add .cursor/skills scripts/skill-shims.manifest.json knowledge/engineering/cursor-skills/audits
git commit -m "chore(skills): manual consolidation pass"
gh pr create --label skills-review --label automated-consolidation

Via the Cursor skill

In a Cursor / OpenCode session, invoke:

/skill-consolidator

Or say “consolidate skills”, “merge new skills into orchestrators”, or “skill consolidation now”. The skill follows the same steps as the script.

Bootstrap mode

One-shot flag that stamps consolidation-review: ignore on every preexisting first-party skill that lacks the field. Already run once; only needed again if a batch of skills lands without the field:

node .github/scripts/propose-skill-consolidations.js --bootstrap

Audit report

Each run produces knowledge/engineering/cursor-skills/audits/YYYY-MM-DD-skill-consolidation.md with sections:

  • Auto-applied consolidations — skills folded into orchestrators this run.
  • Routing-check failures — proposals where the safety check disagreed; surfaced for human review, not applied.
  • Cluster suggestions — themes where 3+ skills could justify a new orchestrator (never auto-created).
  • Kept standalone — eligible skills the model judged genuinely standalone.
  • Rollback — instructions for undoing individual entries or the whole run.

Rollback

For a single skill:

  1. Remove its entry from scripts/skill-shims.manifest.json.
  2. git restore the original SKILL.md.
  3. npm run skills:shims to refresh shims.

For the whole run: git revert the consolidation commit.

Verification

After running, the skill-shim test suite validates everything the consolidator wrote:

npm run test:skill-shims

This suite (433 assertions) checks manifest/disk parity, mode validity against orchestrator headings, and frontmatter shape.

Key files

PathPurpose
.cursor/skills/skill-consolidator/SKILL.mdCursor skill definition (invokable from agents)
.github/scripts/propose-skill-consolidations.jsThe runner — all classification, routing checks, and file mutations
.github/workflows/skill-consolidation.ymlMonday cron + manual dispatch
scripts/skill-shims.manifest.jsonSource of truth for old-skill → orchestrator routing
scripts/generate-skill-shims.mjsRegenerates thin-alias SKILL.md files from the manifest
  • knowledge/engineering/skill-audit.md — historical context for the original consolidation work (PR #1010, PLT-1344)
  • knowledge/engineering/skill-orchestrator-best-practices.md — patterns for mode-driven orchestrators and shim conventions
  • knowledge/engineering/azure-models-for-devs.md — Azure OpenAI deployment details, East US 2 policy
  • weekly-skill-audit skill — advisory layer that flags consolidation candidates without executing

Graph View