optimizing skill

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:

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>                          # 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).

Target 7: Deprecation and Migration (project only)

Coordinate the deprecation, renaming, splitting, or merging of skills. This target ensures all references remain consistent across the project during structural changes.

For the full step-by-step process, see references/deprecation-guide.md.

Deprecation — mark a skill as deprecated without removing it:

1. Add deprecated: true and superseded-by: <project>:<replacement> to the skill's frontmatter
2. Prepend the description with a deprecation notice: "Use when... (deprecated — use <replacement> instead)"
3. Update the bootstrap routing table to note the deprecation
4. Update cross-references in other skills' ## Integration sections

Renaming — change a skill's name while preserving all connections:

1. Rename the directory: skills/old-name/ → skills/new-name/
2. Update frontmatter name field
3. Update all cross-references (<project>:old-name → <project>:new-name) across all SKILL.md, Integration sections, and documentation
4. Update bootstrap routing table
5. Run bundles-forge audit-docs to catch any missed references

Splitting — divide a skill into multiple focused skills:

1. Design the new skill boundaries (reuse bundles-forge:blueprinting scenario B)
2. Invoke bundles-forge:scaffolding for new skill directories
3. Invoke bundles-forge:authoring to write each new skill's content
4. Update all references to the original skill
5. Deprecate the original (or remove if all functionality is covered)
6. Run bundles-forge:auditing in workflow mode to verify chain integrity

Merging — combine multiple skills into one:

1. Design the merged skill (reuse bundles-forge:blueprinting scenario C)
2. Invoke bundles-forge:authoring to write the merged content
3. Deprecate the source skills
4. Update all cross-references and routing
5. Run bundles-forge:auditing in workflow mode

Platform cleanup — after any structural change:

1. Remove deprecated skill references from platform manifests (Cursor plugin.json paths)
2. Update version-bump.json if manifest paths changed
3. Run bundles-forge:testing to verify component discovery

---

Single-Skill Optimization

When the target is a single skill, run only the targets that apply at skill scope. This is auto-detected — no special flags needed.

Applicable Targets

Target	Applicable	What to Do
1. Description Triggering	Full	Evaluate and improve the description's triggering accuracy
2. Content Optimization	Full	Check token budget, references extraction, layer assignment
3. Workflow Chain Integrity	Partial	Fix this skill's W9/W10 findings (Inputs/Outputs clarity, integration symmetry)
4. Security Remediation	Partial	Fix security issues within this skill's content
5. Skill & Workflow Restructuring	Skip	Project-level concern
6. Optional Component Management	Skip	Project-level concern
7. Deprecation and Migration	Skip	Project-level concern
Feedback Iteration	Full	Process user feedback with 3-question validation

Skill Process

1. Read target skill — consume skill-report if available (or extract per-skill findings from audit-report)
2. Determine goal — engineering optimization or feedback iteration?
3. Engineering path: diagnose applicable targets (1-3, partial 4)
4. Feedback path: run the Feedback Iteration process (below)
5. Delegate content changes to bundles-forge:authoring
6. Verify — run bundles-forge:auditing (skill mode) for post-change verification

Script Shortcuts

bundles-forge audit-skill <skill-directory>     # quality checks on single skill

---

Feedback Iteration

Process user feedback about a specific skill's behavior or output quality. This is a cross-cutting concern — available in both project and skill optimization modes. Use this when a user reports that a skill triggered but produced wrong results, skipped steps, or needs better wording.

Classify the Feedback

Signal	Action
"This skill triggered but produced wrong results"	Feedback iteration (below)
"The steps in this skill are in the wrong order"	Feedback iteration (below)
"Description format doesn't follow conventions"	Use optimization targets 1-2
"Token budget exceeded across the project"	Use optimization target 2 (project mode)

The Feedback Process

Receive feedback
  → Identify target skill
  → If external skill: fork with `forked-` prefix before modifying
  → Read skill, understand core goal
  → Validate each feedback item (goal alignment, necessity, side effects)
  → Present improvement plan to user
  → USER CONFIRMS ← gate
  → Copy skill to working version (<skill-name>-optimized/)
  → Delegate changes to bundles-forge:authoring on the copy
  → A/B eval: subagent A (original) vs subagent B (optimized) with same input
  → Present comparison to user
  → User adopts → replace original; User rejects → discard copy
  → Run bundles-forge:auditing for post-change verification

Validation framework — for each feedback item, ask three questions:

1. Goal alignment: Does this serve the skill's core goal, or push it toward a different purpose?
2. Necessity: Without this change, does the skill have an actual defect (vs. a style preference)?
3. Side effects: Could this introduce complexity creep, scope expansion, or regression?

A/B Eval for Feedback Changes

Follow references/ab-eval-protocol.md using the Feedback Iteration context. Compare output quality and behavioral correctness. Skip if the feedback is about structural issues.

Rules:

• Never apply feedback without user confirmation of the improvement plan
• For external skills, always fork first (prefix with forked-, add provenance header)
• After all changes, invoke bundles-forge:auditing for post-change verification — one audit pass only (auditing reports; optimizing decides)

---

Common Mistakes

Mistake	Fix
Optimizing everything at once	Pick one target, measure, improve, verify
Adding MUST/ALWAYS/NEVER instead of explaining why	Explain the reasoning — agents respond to understanding
Splitting skills too aggressively	Only split when there's a genuine responsibility boundary
Ignoring token budget for bootstrap	Bootstrap loads every session — every word counts
Applying feedback without validation	Every item goes through the 3-question framework
Expanding skill scope during any optimization	Optimization should improve how well a skill fulfills its goal, not shift what the goal is. Verify after every change: does this skill still do the same thing?
Running all 7 targets on a single skill	Let scope auto-detection handle it — targets 4-7 don't fully apply
Rewriting entire SKILL.md instead of surgical edits	Specify section-level changes in delegation. A FIX to one heading should not trigger a full rewrite — minimize diff surface to reduce regression risk
Adding third-party skills without security audit	Always run bundles-forge:auditing — see references/third-party-integration.md
Adding skills without updating Integration sections	Every new connection needs symmetric Calls / Called by declarations

Inputs

• audit-report (optional) — findings from bundles-forge:auditing (full project mode). Contains per-skill breakdowns — when optimizing a single skill from a full audit, extract the relevant skill's findings from the Per-Skill Breakdown section
• skill-report (optional) — findings from bundles-forge:auditing (skill mode). More precise input for Skill Optimization — 4-category scored report targeting a single skill
• workflow-report (optional) — workflow-specific findings (W1-W11) from bundles-forge:auditing (workflow mode), consumed by Target 3
• user-feedback (optional) — behavioral feedback about skill quality, triggering issues, or wrong output

Outputs

• optimized-skill — improved SKILL.md content with better descriptions, reduced tokens, or fixed workflow references
• eval-report (optional) — optimization record written to .bundles-forge/evals/, structured as:
  • Action type: FIX, DERIVED, or CAPTURED
  • Change summary: one sentence describing what changed and why
  • Diagnosis basis: which health dimension, audit finding, or user feedback triggered this optimization
  • Before/after comparison: A/B eval results, or verification pass outcome if A/B was skipped

Integration

Called by:

• bundles-forge:releasing — fix quality findings during release pipeline
• User directly — standalone optimization of any project or skill

Calls:

• bundles-forge:authoring — all content changes (descriptions, token optimization, restructuring, third-party adaptation)
  • Artifact: optimized-skill → optimization-spec (indirect — optimizing formulates the spec, authoring receives it as targeted change instructions)
• bundles-forge:scaffolding — Platform Coverage routing for adding new platforms; Optional Component Management target for adding MCP/LSP/userConfig/output-styles
  • Artifact: optimized-skill → project-directory (indirect — scaffolding operates on the project directory, not the optimization output)
• bundles-forge:auditing — post-change verification (one pass, no loops)
  • Artifact: optimized-skill → project-directory (indirect — auditing targets the project containing the optimized skill)

Pairs with:

• bundles-forge:releasing — after optimization, versions may need sync