Jules Integration Skill

Overview

Jules is Google's asynchronous AI coding agent. It runs tasks in the background on a cloud VM, clones your repo, and creates PRs with changes.

When to use Jules:

• Bug fixes that need deep codebase analysis
• Documentation improvements across many files
• Test suite additions
• Code cleanup and refactoring
• Tasks you want to run while you focus elsewhere

When NOT to use Jules:

• Quick, simple changes (do them directly)
• Tasks requiring real-time interaction
• Changes to CI/CD workflows (handle manually)

Prerequisites

1. Jules API Key - Get from https://jules.google (Settings)
2. GitHub connected - Your repo must be connected to Jules
3. AGENTS.md - Should exist in repo root (Jules reads it for context)

Creating a Jules Session

Via API (recommended)

export JULES_API_KEY="your-key-here"

curl 'https://jules.googleapis.com/v1alpha/sessions' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: $JULES_API_KEY" \
  -d '{
    "prompt": "YOUR TASK DESCRIPTION HERE",
    "sourceContext": {
      "source": "sources/github/OWNER/REPO",
      "githubRepoContext": { "startingBranch": "main" }
    },
    "automationMode": "AUTO_CREATE_PR",
    "requirePlanApproval": true
  }'

Via Jules CLI

npm install -g @google/jules
jules login
jules remote new --repo . --session "YOUR TASK"

Via GitHub Actions

Trigger the jules-review.yml workflow manually with your prompt.

Session Workflow

1. Create Session - Jules starts analyzing your codebase
2. Review Plan - Jules generates a plan; approve it at jules.google
3. Monitor Progress - Watch Jules work in real-time
4. Review PR - Jules creates a PR with changes
5. Merge - Review and merge manually

Best Practices

Writing Good Prompts

Do:

• Be specific: "Add unit tests for parseQueryString in utils.js"
• Set constraints: "Do not modify public APIs"
• Define scope: "Focus on the src/auth/ directory"

Don't:

• Be vague: "Make the code better"
• Skip context: "Fix the bug" (which bug?)
• Request unsafe operations: "Auto-merge when done"

Safety Settings

Always use:

• requirePlanApproval: true - Review before Jules acts
• automationMode: "AUTO_CREATE_PR" - Creates PR, doesn't merge
• Check Jules' proposed changes before approving

Monitoring Sessions

# List your sessions
curl 'https://jules.googleapis.com/v1alpha/sessions' \
  -H "X-Goog-Api-Key: $JULES_API_KEY"

# Get session details
curl 'https://jules.googleapis.com/v1alpha/sessions/SESSION_ID' \
  -H "X-Goog-Api-Key: $JULES_API_KEY"

# List activities (progress updates)
curl 'https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities' \
  -H "X-Goog-Api-Key: $JULES_API_KEY"

Troubleshooting

Security Notes

• Never commit API keys - Use environment variables or secrets
• Review all changes - Jules is helpful but not perfect
• Start small - Test with minor tasks before major refactors

Resources

• Jules Web App
• Jules API Docs
• Jules CLI
• Jules Blog Post