optimizing

Optimizing Bundle-Plugins

Overview

Orchestrate targeted improvement of a bundle-plugin project or a single skill. Unlike a full audit, optimization focuses on goals: better triggering, lower token cost, tighter workflow chains, and feedback-driven skill refinement. This skill diagnoses issues, decides on improvements, and delegates content changes to bundles-forge:authoring.

Core principle: Optimize for the agent's experience. Diagnose → decide → delegate → verify.

Skill type: Hybrid — follow the execution flow rigidly (diagnose → decide → delegate → verify), but select targets and adapt execution strategies flexibly based on audit findings and user goals.

Announce at start: "I'm using the optimizing skill to improve [this project / this skill]."

Step 1: Resolve Input & Detect Scope

The target can be a local path, a GitHub URL, or a zip file. Normalize the input to a local directory before scope detection.

Input Normalization

Edge cases & naming conventions: bundles-forge:auditing — references/input-normalization.md

This is a mandatory step — do not skip it or improvise paths. Resolve the target to a local directory before proceeding to Scope Detection.

1. Resolve the workspace. The workspace is $CLAUDE_PROJECT_DIR or $CURSOR_PROJECT_DIR (plugin mode), falling back to the current working directory.
2. Normalize the target by type:
3. Local path — use directly; no transformation needed.
4. GitHub URL — parse <owner> and <repo> from the URL. Shallow-clone to <workspace>/.bundles-forge/repos/<owner>__<repo>/ using --depth 1 --no-checkout, then run git checkout. If the directory already exists, append a __<YYYYMMDD> timestamp to avoid collisions. Do not clone to /tmp/, ~/, or any path outside .bundles-forge/repos/.
5. Zip/tar.gz — extract to <workspace>/.bundles-forge/repos/<archive-name>/.
6. Create the target subdirectory if it does not exist.
7. On failure (network error, 404, auth required, rate limit): tell the user what failed and suggest providing a local path or zip file instead. Do not silently skip or proceed with partial data.

See the canonical source for the full naming convention (version/timestamp suffixes), GitHub subdirectory URLs, and security rules.

Scope Detection

Prerequisites: Target resolved to a local path (via Input Normalization above).

After normalization, determine the scope from the resolved local path:

| Target | How to Detect | Mode | |--------|--------------|------| | Project root | Has skills/ directory and package.json | Project optimization — all 6 targets | | Single skill directory | Contains SKILL.md but no skills/ subdirectory | Skill optimization — 3 targets + feedback iteration | | Single SKILL.md file | Path ends in SKILL.md | Skill optimization — 3 targets + feedback iteration |

If the target is a single skill, skip to the Skill Optimization section below.

Project Optimization

Process

1. Diagnose — run audit scripts, assess skill health, detect workflow gaps
2. Classify & Route — classify action type, select applicable targets
3. Apply — execute selected targets, delegate content changes to authoring
4. Verify — re-audit to confirm improvement

Diagnostic Tools

Audit Script Baseline

Run the quality linter to identify frontmatter issues, description anti-patterns, and broken references before manual optimization:

bundles-forge audit-skill <target-dir>        # markdown report
bundles-forge audit-skill --json <target-dir>  # machine-readable

The linter automates checks Q1-Q15 and X1-X3 from the skill quality ruleset. Focus manual effort on the subjective targets below.

Skill Health Assessment

Assess each skill across four qualitative dimensions: trigger confidence, execution clarity, end-to-end completeness, and degradation signals. See references/optimization-decision-trees.md for the full assessment framework and signal-to-target mapping.

Workflow Gap Detection

When findings reveal structural gaps (not just broken connections but missing capabilities), consider creating new skills via the CAPTURED action type. See references/optimization-decision-trees.md for the gap detection signals.

Routing & Classification

Route findings to targets and classify each action (FIX / DERIVED / CAPTURED) before delegating. See references/optimization-decision-trees.md for:

• Target routing table — maps Q/W/SC findings and user signals to the 6 targets
• Action classification — FIX (repair defect), DERIVED (enhance/specialize), CAPTURED (new skill for gap)
• Pre-delegation checklist — classification rationale, impact analysis, scope preservation

Target 1: Skill Description Triggering

The highest-impact optimization. Descriptions are the primary mechanism for skill discovery.

Diagnosis — identify descriptions that summarize workflow, exceed 250 characters, are too narrow/broad, or fail to start with "Use when...".

Decision — draft the improved description and rationale. Use A/B eval (see below) to compare triggering accuracy before and after.

Delegation — invoke bundles-forge:authoring with a precise change spec: the old description verbatim, the new description, the rationale tied to a specific diagnosis (audit finding, health assessment dimension, or user feedback), and the action classification (FIX/DERIVED). Do not ask authoring to "improve the description" — specify the exact change.

Guiding principle: Use A/B eval when a change could produce regression effects — when improving one dimension might degrade another. Each eval scenario below defines its own skip conditions based on what kind of regression is possible.

A/B Eval for Description Changes

Follow references/ab-eval-protocol.md using the Description Triggering context. Compare trigger rate, false negatives, and false positives. Skip A/B if the change is purely additive.

If subagent dispatch is unavailable: the A/B eval protocol includes a fallback section — ask the user to choose between sequential inline evaluation (read agents/evaluator.md and follow inline) or skipping A/B in favor of a simple verification pass.

Target 2: Content Optimization

Token Budget

Canonical source: Token budgets are defined in bundles-forge:authoring (Token Efficiency section).

Diagnosis — identify skills exceeding token budgets (SKILL.md body > 500 lines, bootstrap > 200 lines), duplicated content, sections that should be in references/.

Decision — determine what to extract, merge, or cut. Map specific sections to their target location.

Delegation — invoke bundles-forge:authoring with a section-level restructuring spec: which sections to extract (source heading → target file in references/), which content to cut (quote the specific lines), and which cross-references to add. Authoring should modify only the named sections, not rewrite the entire SKILL.md.

Layer Assignment

Diagnosis — verify the three-level loading structure (metadata / SKILL.md body / references) is properly layered. Identify skills where the body contains content that belongs at a different level.

Decision — determine which sections to promote (to metadata) or demote (to references/).

Delegation — invoke bundles-forge:authoring with per-section move instructions: for each section being promoted or demoted, specify the source location, the target level, and the reason (e.g. "move lines 45-80 to references/platform-details.md because this content is only needed during platform adaptation, not on every skill load").

Target 3: Workflow Chain Integrity

Consume the workflow-report from bundles-forge:auditing (Workflow mode) to identify and fix workflow issues. If no workflow report is available, run the workflow audit first:

bundles-forge audit-workflow <target-dir>