skill-tuning

Data Community

Repo stars 2,029
Author repo Claude-Code-Workflow

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail fo…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Architecture”, “Core Issues Detected”, “Problem Categories (Detailed Specs)”, “Tuning Strategies (Detailed Specs)”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-tuning directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Architecture / Core Issues Detected / Problem Categories (Detailed Specs)” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Skill Tuning

Autonomous diagnosis and optimization for skill execution issues.

Architecture

┌─────────────────────────────────────────────────────┐
│  Phase 0: Read Specs (mandatory)                    │
│  → problem-taxonomy.md, tuning-strategies.md         │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│  Orchestrator (state-driven)                         │
│  Read state → Select action → Execute → Update → ✓ │
└─────────────────────────────────────────────────────┘
        ↓                           ↓
┌──────────────────────┐   ┌──────────────────┐
│  Diagnosis Phase     │   │ Gemini CLI       │
│  • Context          │   │ Deep analysis    │
│  • Memory           │   │ (on-demand)      │
│  • DataFlow         │   │                  │
│  • Agent            │   │ Complex issues   │
│  • Docs             │   │ Architecture     │
│  • Token Usage      │   │ Performance      │
└──────────────────────┘   └──────────────────┘
                ↓
        ┌───────────────────┐
        │  Fix & Verify     │
        │  Apply → Re-test  │
        └───────────────────┘

Core Issues Detected

Priority	Problem	Root Cause	Fix Strategy
P0	Authoring Violation	Intermediate files, state bloat, file relay	eliminate_intermediate, minimize_state
P1	Data Flow Disruption	Scattered state, inconsistent formats	state_centralization, schema_enforcement
P2	Agent Coordination	Fragile chains, no error handling	error_wrapping, result_validation
P3	Context Explosion	Unbounded history, full content passing	sliding_window, path_reference
P4	Long-tail Forgetting	Early constraint loss	constraint_injection, checkpoint_restore
P5	Token Consumption	Verbose prompts, state bloat	prompt_compression, lazy_loading

Problem Categories (Detailed Specs)

See specs/problem-taxonomy.md for:

Detection patterns (regex/checks)
Severity calculations
Impact assessments

Tuning Strategies (Detailed Specs)

See specs/tuning-strategies.md for:

10+ strategies per category
Implementation patterns
Verification methods

Workflow

Step	Action	Orchestrator Decision	Output
1	`action-init`	status='pending'	Backup, session created
2	`action-analyze-requirements`	After init	Required dimensions + coverage
3	Diagnosis (6 types)	Focus areas	state.diagnosis.{type}
4	`action-gemini-analysis`	Critical issues OR user request	Deep findings
5	`action-generate-report`	All diagnosis complete	state.final_report
6	`action-propose-fixes`	Issues found	state.proposed_fixes[]
7	`action-apply-fix`	Pending fixes	Applied + verified
8	`action-complete`	Quality gates pass	session.status='completed'

Action Reference

Category	Actions	Purpose
Setup	action-init	Initialize backup, session state
Analysis	action-analyze-requirements	Decompose user request via Gemini CLI
Diagnosis	action-diagnose-{context,memory,dataflow,agent,docs,token_consumption}	Detect category-specific issues
Deep Analysis	action-gemini-analysis	Gemini CLI: complex/critical issues
Reporting	action-generate-report	Consolidate findings → final_report
Fixing	action-propose-fixes, action-apply-fix	Generate + apply fixes
Verify	action-verify	Re-run diagnosis, check gates
Exit	action-complete, action-abort	Finalize or rollback

Full action details: phases/actions/

State Management

Single source of truth: .workflow/.scratchpad/skill-tuning-{ts}/state.json

{
  "status": "pending|running|completed|failed",
  "target_skill": { "name": "...", "path": "..." },
  "diagnosis": {
    "context": {...},
    "memory": {...},
    "dataflow": {...},
    "agent": {...},
    "docs": {...},
    "token_consumption": {...}
  },
  "issues": [{"id":"...", "severity":"...", "category":"...", "strategy":"..."}],
  "proposed_fixes": [...],
  "applied_fixes": [...],
  "quality_gate": "pass|fail",
  "final_report": "..."
}

See phases/state-schema.md for complete schema.

Orchestrator Logic

See phases/orchestrator.md for:

Decision logic (termination checks → action selection)
State transitions
Error recovery

Key Principles

Problem-First: Diagnosis before any fix
Data-Driven: Record traces, token counts, snapshots
Iterative: Multiple rounds until quality gates pass
Reversible: All changes with backup checkpoints
Non-Invasive: Minimal changes, maximum clarity

Usage Examples

# Basic skill diagnosis
/skill-tuning "Fix memory leaks in my skill"

# Deep analysis with Gemini
/skill-tuning "Architecture issues in async workflow"

# Focus on specific areas
/skill-tuning "Optimize token consumption and fix agent coordination"

# Custom issue
/skill-tuning "My skill produces inconsistent outputs"

Output

After completion, review:

.workflow/.scratchpad/skill-tuning-{ts}/state.json - Full state with final_report
state.final_report - Markdown summary (in state.json)
state.applied_fixes - List of applied fixes with verification results

Reference Documents

Document	Purpose
specs/problem-taxonomy.md	Classification + detection patterns
specs/tuning-strategies.md	Fix implementation guide
specs/dimension-mapping.md	Dimension ↔ Spec mapping
specs/quality-gates.md	Quality verification criteria
phases/orchestrator.md	Workflow orchestration
phases/state-schema.md	State structure definition
phases/actions/	Individual action implementations

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Data
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @catlog22 · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-tuning.preview

# Usage Examples

# Basic skill diagnosis
/skill-tuning "Fix memory leaks in my skill"

# Deep analysis with Gemini
/skill-tuning "Architecture issues in async workflow"

# Focus on specific areas
/skill-tuning "Optimize token consumption and fix agent coordination"

# Custom issue
/skill-tuning "My skill produces inconsistent outputs"

SKILL.md SKILL.md

# Skill Tuning

Autonomous diagnosis and optimization for skill execution issues.

## Architecture

```
┌─────────────────────────────────────────────────────┐
│  Phase 0: Read Specs (mandatory)                    │
│  → problem-taxonomy.md, tuning-strategies.md         │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│  Orchestrator (state-driven)                         │
│  Read state → Select action → Execute → Update → ✓ │
└─────────────────────────────────────────────────────┘
        ↓                           ↓
┌──────────────────────┐   ┌──────────────────┐
│  Diagnosis Phase     │   │ Gemini CLI       │
│  • Context          │   │ Deep analysis    │
│  • Memory           │   │ (on-demand)      │
│  • DataFlow         │   │                  │
│  • Agent            │   │ Complex issues   │
│  • Docs             │   │ Architecture     │
│  • Token Usage      │   │ Performance      │
└──────────────────────┘   └──────────────────┘
                ↓
        ┌───────────────────┐
        │  Fix & Verify     │
        │  Apply → Re-test  │
        └───────────────────┘
```

## Core Issues Detected

| Priority | Problem | Root Cause | Fix Strategy |
|----------|---------|-----------|--------------|
| **P0** | Authoring Violation | Intermediate files, state bloat, file relay | eliminate_intermediate, minimize_state |
| **P1** | Data Flow Disruption | Scattered state, inconsistent formats | state_centralization, schema_enforcement |
| **P2** | Agent Coordination | Fragile chains, no error handling | error_wrapping, result_validation |
| **P3** | Context Explosion | Unbounded history, full content passing | sliding_window, path_reference |

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Architecture → Core Issues Detected → Problem Categories (Detailed Specs) → Tuning Strategies (Detailed Specs) → Workflow → Action Reference
terms    -> P0 · P1 · P2 · P3 · P4 · P5 · Setup · Analysis
files/cmd -> action-init · action-analyze-requirements · action-gemini-analysis · action-generate-report · action-propose-fixes · action-apply-fix · action-complete · .workflow/.scratchpad/skill-tuning-{ts}/state.json
body sha256 -> cf9a26970891