optimizing skill
説明文の改善、トークン使用量の削減、監査結果の修正、およびワークフローの再構築により、bundle-pluginsと個別のSKILLを最適化します。
- GitHubスター
- 225
- ファイル
- 6
- 最終コミット
- 2026年4月27日
- ライセンス
- Apache-2.0
- 許可されたツール
- 18
optimizing skillは何をしますか
optimizingはAgent Skillsです。 説明文の改善、トークン使用量の削減、監査結果の修正、およびワークフローの再構築により、bundle-pluginsと個別のSKILLを最適化します。.
skillのSKILL.mdから生成された要約。
optimizing skill について
このツールは、bundle-pluginsや個別のSKILLのパフォーマンスと効率を向上させます。SKILLの発見性を高め、トークン消費を抑え、ワークフローの構造的な欠陥を修正することで、エージェントの体験を洗練させたい開発者向けに設計されています。すべての変更が品質基準を満たすよう、診断、決定、委譲、検証という厳格なサイクルに従ってプロセスが進められます。
エージェントがこのSKILLをロードすると、ローカルディレクトリ、GitHubリポジトリ、または圧縮アーカイブを対象にできます。bundles-forge audit-skill、audit-security、audit-docs、audit-plugin、audit-workflowなどの診断ツール群を活用して、特定の問題を特定します。問題が検出されると、実際のコンテンツ修正は bundles-forge:authoring ツールに委譲されます。これにより、SKILLの説明文の精密な更新、コンテンツ抽出によるトークン予算の管理、および監査中に発見されたセキュリティ脆弱性の修正が可能になります。
エージェントができること
- 1SKILLの発見性を向上説明文を精査してエージェントの意図との一致度を高めることで、SKILLのトリガー精度を向上させます。
- 2トークン消費量を削減SKILL.mdファイルから過剰なコンテンツを特定・抽出することで、定義されたトークン予算内に収めます。
- 3ワークフローの欠落を修正プロジェクト内の不足している機能を検出し、ワークフローチェーンを完結させるための新しいSKILLを作成します。
- 4セキュリティの脆弱性を修正不要なシステムアクセスを削除したり、フック内でのネットワーク呼び出しの正当性を確認したりすることで、セキュリティ上の脆弱性に対処します。
skill の SKILL.md から作成されています。すべてのユースケースは、その引用と照合されています。
optimizing skillのインストール方法
各コマンドはskillフォルダをクライアントのskillsディレクトリにコピーします。読み込むには、クライアントを再起動するか新しいセッションを開始してください。プラグインにoptimizing skillをインストールする
/plugin marketplace add OdradekAI/bundles-forge /plugin install bundles-forge@bundles-forge-dev
Claude Codeにoptimizing skillをインストールする
~/.claude/skills/optimizing/SKILL.md
$ npx degit OdradekAI/bundles-forge/skills/optimizing ~/.claude/skills/optimizingClaude Code (project)にoptimizing skillをインストールする
.claude/skills/optimizing/SKILL.md
$ npx degit OdradekAI/bundles-forge/skills/optimizing .claude/skills/optimizingCodexにoptimizing skillをインストールする
~/.agents/skills/optimizing/SKILL.md
$ npx degit OdradekAI/bundles-forge/skills/optimizing ~/.agents/skills/optimizingGemini CLIにoptimizing skillをインストールする
~/.gemini/skills/optimizing/SKILL.md
$ npx degit OdradekAI/bundles-forge/skills/optimizing ~/.gemini/skills/optimizingClaude.aiにoptimizing skillをインストールする
npx degit OdradekAI/bundles-forge/skills/optimizing optimizing && zip -r optimizing.zip optimizing # claude.ai → Customize → Skills → + → Create skill → Upload a skill → optimizing.zip
SKILL.md
GitHubで表示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> # 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:
- Add
deprecated: trueandsuperseded-by: <project>:<replacement>to the skill's frontmatter - Prepend the description with a deprecation notice:
"Use when... (deprecated — use <replacement> instead)" - Update the bootstrap routing table to note the deprecation
- Update cross-references in other skills'
## Integrationsections
Renaming — change a skill's name while preserving all connections:
- Rename the directory:
skills/old-name/→skills/new-name/ - Update frontmatter
namefield - Update all cross-references (
<project>:old-name→<project>:new-name) across all SKILL.md, Integration sections, and documentation - Update bootstrap routing table
- Run
bundles-forge audit-docsto catch any missed references
Splitting — divide a skill into multiple focused skills:
- Design the new skill boundaries (reuse
bundles-forge:blueprintingscenario B) - Invoke
bundles-forge:scaffoldingfor new skill directories - Invoke
bundles-forge:authoringto write each new skill's content - Update all references to the original skill
- Deprecate the original (or remove if all functionality is covered)
- Run
bundles-forge:auditingin workflow mode to verify chain integrity
Merging — combine multiple skills into one:
- Design the merged skill (reuse
bundles-forge:blueprintingscenario C) - Invoke
bundles-forge:authoringto write the merged content - Deprecate the source skills
- Update all cross-references and routing
- Run
bundles-forge:auditingin workflow mode
Platform cleanup — after any structural change:
- Remove deprecated skill references from platform manifests (Cursor plugin.json paths)
- Update version-bump.json if manifest paths changed
- Run
bundles-forge:testingto 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
- Read target skill — consume
skill-reportif available (or extract per-skill findings fromaudit-report) - Determine goal — engineering optimization or feedback iteration?
- Engineering path: diagnose applicable targets (1-3, partial 4)
- Feedback path: run the Feedback Iteration process (below)
- Delegate content changes to
bundles-forge:authoring - 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:
- Goal alignment: Does this serve the skill's core goal, or push it toward a different purpose?
- Necessity: Without this change, does the skill have an actual defect (vs. a style preference)?
- 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:auditingfor 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 frombundles-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 frombundles-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) frombundles-forge:auditing(workflow mode), consumed by Target 3user-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 referenceseval-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)
- Artifact:
- 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)
- Artifact:
- bundles-forge:auditing — post-change verification (one pass, no loops)
- Artifact:
optimized-skill→project-directory(indirect — auditing targets the project containing the optimized skill)
- Artifact:
Pairs with:
- bundles-forge:releasing — after optimization, versions may need sync
このスキルのファイル
6optimizing skillに関する質問
Claude Codeにoptimizing skillをインストールするには
npx degit OdradekAI/bundles-forge/skills/optimizing ~/.claude/skills/optimizingを実行してください。Claude Codeは~/.claude/skills(すべてのプロジェクト)または.claude/skills(単一プロジェクト)からskillsを読み込み、説明がタスクに一致する場合にskillを使用します。
optimizing skillはどのクライアントで使用できますか
Agent Skills形式を読み込むすべてのクライアントで使用できます: Claude Code、Codex、Gemini CLI、claude.ai(ZIPとしてアップロード)。skill内のスクリプトは、クライアントがコード実行を許可した場合にのみ実行されます。
最適化SKILLの核となる原則は何ですか?
Diagnose(診断)→ decide(決定)→ delegate(委譲)→ verify(検証)というワークフローを用いて、エージェントの体験を最適化することを原則としています。
最適化の際、GitHubのURLはどのように処理されますか?
オーナー名とリポジトリ名を解析し、.bundles-forge/repos/内の特定のローカルディレクトリにシャロークローンを実行した後、git checkoutを行います。
トークン使用量に関してどのような最適化が可能ですか?
500行を超えるSKILL.mdの本文や、200行を超えるブートストラップなど、トークン予算を超過しているSKILLを特定し、抽出または削減すべきコンテンツを提案します。