/optimizing

name: optimizing
description: "Use when optimizing a bundle-plugin or single skill — improving descriptions, reducing tokens, fixing audit findings, restructuring workflows, adding skills to fill gaps, or iterating on user feedback"
allowed-tools: Bash(bundles-forge audit-skill *) Bash(bundles-forge audit-security *) Bash(bundles-forge audit-docs *) Bash(bundles-forge audit-plugin *) Bash(bundles-forge audit-workflow *) Bash(bundles-forge checklists *)

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 desc