Skill Tuning

What it does

When your agent uses it

• Skill diagnosis
• Tasks that involve Multi-agent orchestration

Example prompts

• “skill tuning”
• “tune skill”
• “skill diagnosis”
• “/skill-tuning”

Requirements

• Pre-approved tools (allowed-tools): Agent, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit 07491b0. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Agent
  • AskUserQuestion
  • Read
  • Write
  • Bash
  • Glob
  • Grep
  • mcp__ace-tool__search_context

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are json and bash).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Skill Tuning loads about 1.7k tokens when it runs. Until then it costs about 85 tokens; SKILL.md has 341 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~85

When it runs · the whole SKILL.md, loaded when a task matches

~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NotePre-approves every shell command (allowed-tools: Bash)SKILL.md

  allowed-tools: Agent, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from catlog22/Claude-Code-Workflow at commit 07491b0, republished under its MIT licence (© catlog22). 341 words, ~1,671 tokens.

name

skill-tuning

description

Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail forgetting, data flow disruption, and agent coordination failures. Supports Gemini CLI for deep analysis. Triggers on "skill tuning", "tune skill", "skill diagnosis", "optimize skill", "skill debug".

allowed-tools

Agent, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context

┌─────────────────────────────────────────────────────┐
│  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  │
        └───────────────────┘

{
  "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": "..."
}

# 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"

© catlog22, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 27 other files in .claude/skills/skill-tuning of catlog22/Claude-Code-Workflow.

• SKILL.md
• phases/actions/action-abort.md
• phases/actions/action-analyze-requirements.md
• phases/actions/action-apply-fix.md
• phases/actions/action-complete.md
• phases/actions/action-diagnose-agent.md
• phases/actions/action-diagnose-context.md
• phases/actions/action-diagnose-dataflow.md
• phases/actions/action-diagnose-docs.md
• phases/actions/action-diagnose-memory.md
• phases/actions/action-diagnose-token-consumption.md
• phases/actions/action-gemini-analysis.md
• phases/actions/action-generate-report.md
• phases/actions/action-init.md
• phases/actions/action-propose-fixes.md
• phases/actions/action-verify.md
• phases/orchestrator.md
• phases/state-schema.md
• specs
• … and 9 more

Open the folder on GitHubat commit 07491b0

Used in 1 other repository

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders. This page covers the copy in catlog22/Claude-Code-Workflow, which our catalogue first saw on October 7, 2026.

• catlog22/maestro-flow.codex/skills/skill-tuning.claude/skills/skill-tuning