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:
   • Local path — use directly; no transformation needed.
   • 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/.
   • Zip/tar.gz — extract to <workspace>/.bundles-forge/repos/<archive-name>/.
3. Create the target subdirectory if it does not exist.
4. 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:

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>                          # full workflow audit
bundles-forge audit-workflow --focus-skills skill-a,skill-b <root>   # focused on specific skills

Fix by W-check priority: See references/optimization-decision-trees.md for the full W1-W10 fix table.

After fixes — Chain A/B Eval:

Follow references/ab-eval-protocol.md using the Chain Integrity context. Use after modifying Inputs/Outputs sections, adding new skills to a chain, or when W1-W4 findings indicate integrity issues.

Target 4: Security Remediation (project only)

Fix security findings from bundles-forge:auditing Category 10.

Targets:

• Remove unnecessary system access from hook scripts (least privilege)
• Scope OpenCode plugin capabilities to declared needs only
• Remove or justify any network calls in hooks/plugins
• Ensure agent prompts include scope constraints
• Strip encoding tricks or obfuscated content from SKILL.md files

Process: Run security scan first, then address findings by priority — critical before warnings, warnings before info:

bundles-forge audit-security <target-dir>

Alternatively, invoke bundles-forge:auditing for a full audit that includes security (Category 10).

Target 5: Skill & Workflow Restructuring (project only)

Structural changes to achieve user goals: adding skills, replacing skills, reorganizing workflow chains, or converting skills to subagents. See references/restructuring-operations.md for the full step-by-step procedures (5a Adding, 5b Replacing, 5c Reorganizing, 5d Skill-to-Agent Conversion).

Target 6: Optional Component Management (project only)

Add, adjust, or migrate optional plugin components based on evolving project needs. This target handles the gap between initial scaffolding and the components a project needs as it matures.

Diagnosis — identify signals that a component is needed. See references/optimization-decision-trees.md for the full signal-to-component mapping table (userConfig, MCP, LSP, output-styles, PLUGIN_DATA, path migration).

Decision — read bundles-forge:scaffolding — references/external-integration.md for the full decision tree (CLI vs MCP, userConfig schema, PLUGIN_DATA patterns, LSP fields, output-styles format, settings.json scope).

Execution — invoke bundles-forge:scaffolding using its "Adding Optional Components" flow. Scaffolding handles file generation, manifest updates, and inspector validation.

Verification — after scaffolding completes, run bundles-forge:auditing to confirm structural integrity and security compliance (especially for new MCP servers and userConfig sensitive values).