菜单
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
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when reviewing a bundle-plugin for structural issues, version drift, skill quality, workflow integration, or security risks — before releasing, after changes, or after adding skills. Auto-detects scope (full project vs skill vs workflow)
Use when writing, completing, improving, or adapting SKILL.md and agents/*.md in a bundle-plugin — integrating external skills, filling scaffolded stubs, or rewriting for better triggering and token efficiency
Use when generating project structure for new bundle-plugins, adding or removing platform support (Claude Code, Cursor, Codex, OpenCode, Gemini CLI, OpenClaw), updating platform manifests, or migrating hooks and configuration between platforms
Use when planning new bundle-plugins, splitting complex skills, combining skills into bundles, or exploring a vague idea about packaging skills
Use when releasing a bundle-plugin, bumping versions, fixing version drift across manifests, setting up version sync infrastructure, updating CHANGELOG, publishing to marketplaces, or checking release readiness
Use when testing a bundle-plugin locally before release — generating dev-marketplace environments, verifying component discovery, running hook smoke tests, and validating cross-platform readiness
基于 SOC 职业分类
| 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 *) |
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]."
The target can be a local path, a GitHub URL, or a zip file. Normalize the input to a local directory before scope detection.
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.
$CLAUDE_PROJECT_DIR or $CURSOR_PROJECT_DIR (plugin mode), falling back to the current working directory.<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/.<workspace>/.bundles-forge/repos/<archive-name>/.See the canonical source for the full naming convention (version/timestamp suffixes), GitHub subdirectory URLs, and security rules.
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.
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.
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.
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.
Route findings to targets and classify each action (FIX / DERIVED / CAPTURED) before delegating. See references/optimization-decision-trees.md for:
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.
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.
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.
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").
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.
Fix security findings from bundles-forge:auditing Category 10.
Targets:
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).
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).
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).
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:
deprecated: true and superseded-by: <project>:<replacement> to the skill's frontmatter"Use when... (deprecated — use <replacement> instead)"## Integration sectionsRenaming — change a skill's name while preserving all connections:
skills/old-name/ → skills/new-name/name field<project>:old-name → <project>:new-name) across all SKILL.md, Integration sections, and documentationbundles-forge audit-docs to catch any missed referencesSplitting — divide a skill into multiple focused skills:
bundles-forge:blueprinting scenario B)bundles-forge:scaffolding for new skill directoriesbundles-forge:authoring to write each new skill's contentbundles-forge:auditing in workflow mode to verify chain integrityMerging — combine multiple skills into one:
bundles-forge:blueprinting scenario C)bundles-forge:authoring to write the merged contentbundles-forge:auditing in workflow modePlatform cleanup — after any structural change:
bundles-forge:testing to verify component discoveryWhen the target is a single skill, run only the targets that apply at skill scope. This is auto-detected — no special flags needed.
| 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-report if available (or extract per-skill findings from audit-report)bundles-forge:authoringbundles-forge:auditing (skill mode) for post-change verificationbundles-forge audit-skill <skill-directory> # quality checks on single skill
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.
| 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) |
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:
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:
forked-, add provenance header)bundles-forge:auditing for post-change verification — one audit pass only (auditing reports; optimizing decides)| 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 |
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 sectionskill-report (optional) — findings from bundles-forge:auditing (skill mode). More precise input for Skill Optimization — 4-category scored report targeting a single skillworkflow-report (optional) — workflow-specific findings (W1-W11) from bundles-forge:auditing (workflow mode), consumed by Target 3user-feedback (optional) — behavioral feedback about skill quality, triggering issues, or wrong outputoptimized-skill — improved SKILL.md content with better descriptions, reduced tokens, or fixed workflow referenceseval-report (optional) — optimization record written to .bundles-forge/evals/, structured as:
Called by:
Calls:
optimized-skill → optimization-spec (indirect — optimizing formulates the spec, authoring receives it as targeted change instructions)optimized-skill → project-directory (indirect — scaffolding operates on the project directory, not the optimization output)optimized-skill → project-directory (indirect — auditing targets the project containing the optimized skill)Pairs with: