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.
- Resolve the workspace. The workspace is
$CLAUDE_PROJECT_DIRor$CURSOR_PROJECT_DIR(plugin mode), falling back to the current working directory. - 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 rungit 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>/.
- Create the target subdirectory if it does not exist.
- 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
- Diagnose — run audit scripts, assess skill health, detect workflow gaps
- Classify & Route — classify action type, select applicable targets
- Apply — execute selected targets, delegate content changes to authoring
- 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>