optimize-skill

name	optimize-skill
description	Analyze agent skills to find deterministic command chains that should be extracted into scripts. Follows the principle: use AI to decide which tool to call, not to execute deterministic logic repeatedly. Triggers: /optimize-skill, "optimize this skill", "extract deterministic commands", "refactor this skill", "find command chains to extract"
user_invocable	true
argument-hint	[path to skill or skills directory]

Optimize Skill - Extract Deterministic Commands

Analyze agent skills and extract multi-step deterministic command chains into standalone scripts.

When to Use

• User says "optimize this skill", "check if we can improve this skill"
• User points to a skill directory or SKILL.md file
• After creating a new skill with complex command sequences
• Periodic skill maintenance/refactoring

Principle

From "Stop Using AI For This" video:

Don't make AI execute deterministic logic repeatedly. Write the logic once as a script, let AI decide when to call it.

What to Extract

Extract when you see:

1. Multi-step pipelines — query → filter → transform → output

   # Before: encoded in skill
   curl ... | jq '.data' | filter | transform
   

   # After: single script call
   ~/.agents/skills/foo/scripts/fetch-data.sh
   

2. Parallel operations — multiple commands with wait/merge logic

   # Before: skill describes parallel pattern
   for repo in ...; do cmd & done; wait; merge
   

   # After: script handles parallelism
   ~/.agents/skills/foo/scripts/gather-parallel.sh
   

3. Complex conditionals — date calculations, token extraction, nested if/else

   # Before: case statement in skill
   case "$DAY" in Sat) date -d "3 days ago" ;; ...
   

   # After: script handles logic
   ~/.agents/skills/foo/scripts/calculate-date.sh
   

4. GraphQL/API queries — hardcoded query structure with filtering

   # Before: 10+ lines of query + curl + jq
   curl -H "..." -d '{"query":"... 100 chars ..."}'
   

   # After: script encapsulates query
   ~/.agents/skills/foo/scripts/graphql-query.sh
   

5. Data gathering that's reused — same fetch pattern across skills

   # Can be shared across skills
   ~/.agents/skills/common/scripts/fetch-sprint-tickets.sh
   

Do NOT extract:

• Single CLI tool calls (jira issue list ...)
• Simple file operations (cat, echo, basic jq)
• Context-dependent decisions (which skill to invoke, which tool to use)
• Commands where arguments vary significantly each time
• Operations that need immediate user feedback

Analysis Steps

1. Read the Skill

Read the SKILL.md file(s) in the target directory.

2. Identify Command Patterns

Scan for these patterns:

• Code blocks with bash or sh language
• Multi-line command sequences
• Hardcoded queries or data structures
• Comments like "run in parallel", "wait for all", "filter results"
• Repeated patterns (same command structure appears multiple times)
• Token calculations (date math, string extraction, credential fetching)

3. Score Each Command Block

For each command block, score on:

• Complexity: 0 (single command) to 5 (multi-step pipeline)
• Determinism: 0 (highly variable) to 5 (always runs the same)
• Reusability: 0 (one-off) to 5 (used across skills)
• Token cost: estimate tokens saved per invocation

Extract if: Complexity ≥ 2 AND Determinism ≥ 3

4. Group Related Commands

Look for:

• Commands that always run together
• Commands with shared setup (export variables, cd to directory)
• Commands that feed into each other (output of A → input of B)

5. Propose Scripts

For each extraction candidate, propose:

• Script name and location (scripts/<name>.sh)
• Script purpose (comment header)
• Input parameters (if any)
• Output format (JSON, text, exit code)
• Error handling strategy

6. Show Before/After

Present side-by-side:

Before:

### Step 3: Fetch Data
\`\`\`bash
TOKEN=$(security find-generic-password -s "..." -w)
if [[ "$TOKEN" == go-keyring-base64:* ]]; then
  TOKEN=$(echo "${TOKEN#go-keyring-base64:}" | base64 -d)
fi
curl -H "Authorization: bearer $TOKEN" \
  -d '{"query":"..."}' https://api.github.com/graphql | jq '.data.nodes'
\`\`\`

After:

### Step 3: Fetch Data
\`\`\`bash
~/.agents/skills/skill-name/scripts/fetch-github-data.sh
\`\`\`
Returns JSON array of nodes.

Script: scripts/fetch-github-data.sh

#!/usr/bin/env bash
set -e
# Fetch GitHub data via GraphQL
# Returns: JSON array of nodes
TOKEN=$(security find-generic-password -s "gh:github.com" -w 2>&1)
if [[ "$TOKEN" == go-keyring-base64:* ]]; then
  TOKEN=$(echo "${TOKEN#go-keyring-base64:}" | base64 -d)
fi
curl -s -H "Authorization: bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"{ ... }"}' https://api.github.com/graphql | jq -c '.data.nodes'

7. Estimate Impact

Calculate savings:

• Token reduction per skill invocation
• Number of times skill is typically invoked per day/week
• Total weekly token savings
• Reliability improvement (deterministic execution)

8. Ask for Confirmation

Present the analysis and proposed changes. Ask:

1. Should I create these scripts?
2. Should I update the skill file to reference them?
3. Any scripts to skip or modify?

9. Implement (if approved)

For each approved script:

1. Create scripts/ directory in skill folder if needed
2. Write script with proper shebang, error handling, comments
3. Make executable (chmod +x)
4. Update SKILL.md to replace inline commands with script call
5. Test the script (run it, check output format)
6. Report any issues

10. Document Changes

Create a summary file at /tmp/skill-optimization-<skill-name>.md:

• Scripts created
• Skill sections modified
• Token savings estimate
• Test results

Output Format

Present findings as:

# Skill Optimization Analysis: <skill-name>

## Summary
- X command blocks analyzed
- Y extraction candidates found
- Estimated Z tokens saved per invocation

## Candidates for Extraction

### 1. <name> (Complexity: 4, Determinism: 5, Tokens: ~150)
**Current:** Steps 3-4 in SKILL.md (lines X-Y)
**Proposed:** `scripts/<name>.sh`
**Savings:** ~150 tokens per invocation
**Rationale:** Multi-step pipeline with hardcoded GraphQL query

[Show before/after]

### 2. <name> (Complexity: 3, Determinism: 4, Tokens: ~80)
...

## Scripts NOT Worth Extracting

### Step 6: Simple file read
**Reason:** Single command, context-dependent path
**Keep as-is:** `cat /path/to/file`

## Recommendations

1. Extract candidates 1, 2, 4 (high impact)
2. Leave candidates 3, 5 inline (low complexity)
3. Consider sharing candidate 2 with <other-skill>

Proceed? [y/n]

Edge Cases

• Skill uses MCP tools: Don't extract MCP calls, they're already encapsulated
• Skill has existing scripts/: Analyze if they can be improved or consolidated
• Multi-skill extraction: If multiple skills share a pattern, propose a shared script location
• Sandbox requirements: Note if scripts need dangerouslyDisableSandbox: true
• Credentials: Ensure scripts handle token/password extraction properly

Testing Protocol

For each created script:

1. Run with typical inputs
2. Verify output format matches expectations
3. Check error handling (missing deps, failed commands)
4. Test cross-platform compatibility (GNU vs BSD date, etc.)
5. Ensure it works from skill context (paths, environment)

Common pitfalls to check:

• Tab-delimited output: If parsing --plain output from CLIs, check for variable tab alignment. Prefer --raw or --json flags when available.
• Date commands: Use date --version to detect GNU vs BSD, not uname
• Temp files: Use mktemp for safe temp filenames, especially when names contain slashes
• JSON parsing: Always prefer native JSON output (--raw, --json) over parsing formatted text

Tool-specific flags:

• jira issue list --raw → JSON array of issues
• jira sprint list --plain → No JSON mode, grep/awk is fine
• gh pr list --json <fields> → JSON output
• confluence search --cql → No JSON mode, text parsing necessary

Examples

See existing optimized skills:

• backlog/scripts/ — date calculation, GraphQL query, sprint tickets (uses --raw)
• my-weekly-report/scripts/ — parallel PR fetching, confluence search
• copy-for-teams/copy_teams.py — clipboard HTML formatting
• recall/scripts/ — session search and reading

Key improvements from testing:

• sprint-tickets.sh: Switched from --plain --columns to --raw for reliable JSON parsing
• user-prs.sh: Used mktemp instead of hardcoded temp file paths with slashes
• date-before.sh: Detects date command flavor via --version, not OS name

Notes

• Always show full before/after for user review
• Don't optimize prematurely — wait for complexity to appear
• Scripts should be self-contained and testable
• Prefer simple bash over complex awk/sed unless necessary
• Use jq for JSON manipulation when available
• Test scripts with real data before committing — tab alignment, temp files, date commands all have edge cases