Optimize Skill

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