Initial commit
This commit is contained in:
Zhongwei Li
277
SKILL.md
Normal file
277
SKILL.md
Normal file
@@ -0,0 +1,277 @@
|
||||
---
|
||||
name: headless-cli-agents
|
||||
description: This skill provides comprehensive guidance for running AI coding agents in non-interactive (headless) mode for automation, CI/CD pipelines, and scripting. Use when integrating Claude Code, Codex, Gemini, OpenCode, Qwen, or Droid CLI into automated workflows where human interaction is not desired.
|
||||
---
|
||||
|
||||
# Headless CLI Agents
|
||||
|
||||
## Overview
|
||||
|
||||
This skill enables the use of AI coding agents in non-interactive mode for automation scenarios. It provides command references, safety considerations, and practical examples for integrating AI agents into CI/CD pipelines, shell scripts, and other automated workflows.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Agent | Basic Command | Automation Flag | Best For |
|
||||
|-------|--------------|----------------|----------|
|
||||
| Claude Code | `claude -p "prompt"` | Auto-approved by default | General coding tasks |
|
||||
| OpenAI Codex | `codex exec "prompt"` | `--full-auto` | Complex refactoring |
|
||||
| Google Gemini | `gemini -p "prompt"` | `--yolo` (if available) | Analysis tasks |
|
||||
| OpenCode | `opencode -p "prompt"` | Auto-approved by default | Multi-provider support |
|
||||
| Qwen Code | `qwen -p "prompt"` | `--yolo` | Local model support |
|
||||
| Factory Droid | `droid exec "prompt"` | `--auto <level>` | Controlled automation |
|
||||
|
||||
## When to Use Headless Mode
|
||||
|
||||
Use this skill when:
|
||||
- **CI/CD Pipelines**: Automated code reviews, test generation, documentation
|
||||
- **Shell Scripts**: Repetitive coding tasks, bulk operations
|
||||
- **Cron Jobs**: Scheduled maintenance, analysis tasks
|
||||
- **Git Hooks**: Pre-commit validation, post-commit analysis
|
||||
- **DevOps Automation**: Infrastructure as code, deployment preparation
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### 1. Agent Selection
|
||||
|
||||
Choose the appropriate agent based on your requirements:
|
||||
|
||||
**Claude Code CLI** - Best for general-purpose coding with excellent code understanding
|
||||
```bash
|
||||
# Basic usage
|
||||
claude -p "Review this code for security issues"
|
||||
|
||||
# With additional context
|
||||
claude -p "Generate tests for authentication module" --add-dir ./tests
|
||||
```
|
||||
|
||||
**OpenAI Codex CLI** - Best for complex refactoring and code transformation
|
||||
```bash
|
||||
# Automated refactoring
|
||||
codex exec --full-auto "Refactor this module to use async/await"
|
||||
|
||||
# Outside git repos
|
||||
codex exec --skip-git-repo-check --full-auto "Create API documentation"
|
||||
```
|
||||
|
||||
**Google Gemini CLI** - Best for analysis and documentation tasks
|
||||
```bash
|
||||
# Analysis with structured output
|
||||
gemini -p "Analyze codebase architecture" --output-format json
|
||||
|
||||
# Documentation generation
|
||||
cat src/ | gemini -p "Generate comprehensive API documentation"
|
||||
```
|
||||
|
||||
### 2. Safety and Autonomy Levels
|
||||
|
||||
Different agents provide varying levels of automation control:
|
||||
|
||||
**Read-Only Mode (Safest)**
|
||||
```bash
|
||||
# Analysis without changes
|
||||
droid exec "Analyze security vulnerabilities"
|
||||
gemini -p "Review code quality metrics"
|
||||
```
|
||||
|
||||
**Low-Risk Changes**
|
||||
```bash
|
||||
# Documentation and comments
|
||||
droid exec "Add docstrings to all functions" --auto low
|
||||
codex exec --full-auto "Update README with installation instructions"
|
||||
```
|
||||
|
||||
**Development Operations**
|
||||
```bash
|
||||
# Package installation, test running
|
||||
droid exec "Install dependencies and run tests" --auto medium
|
||||
codex exec --full-auto "Fix failing unit tests"
|
||||
```
|
||||
|
||||
**High-Risk Changes (Use Carefully)**
|
||||
```bash
|
||||
# Production deployments, major refactoring
|
||||
droid exec "Implement OAuth2 migration" --auto high
|
||||
# Only in isolated environments
|
||||
codex exec --yolo "Complete system refactoring"
|
||||
```
|
||||
|
||||
### 3. Input/Output Patterns
|
||||
|
||||
**Piping Content**
|
||||
```bash
|
||||
# Analyze git diff
|
||||
git diff | claude -p "Review these changes for bugs"
|
||||
|
||||
# Process error logs
|
||||
cat error.log | qwen -p "Categorize and summarize these errors"
|
||||
|
||||
# Multiple files
|
||||
find . -name "*.py" | xargs claude -p "Check for anti-patterns"
|
||||
```
|
||||
|
||||
**File-based Prompts**
|
||||
```bash
|
||||
# Read from prompt file
|
||||
droid exec -f migration_prompt.md
|
||||
|
||||
# JSON output for parsing
|
||||
gemini -p "List all API endpoints" --output-format json
|
||||
```
|
||||
|
||||
**Structured Output**
|
||||
```bash
|
||||
# Machine-readable output
|
||||
opencode -p "Count lines of code" -f json
|
||||
claude -p "Generate test coverage report" > coverage_report.md
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Code Review Automation
|
||||
```bash
|
||||
# Quick security scan
|
||||
find . -name "*.py" | xargs claude -p "Check for security vulnerabilities"
|
||||
|
||||
# Performance analysis
|
||||
git diff | codex exec --full-auto "Analyze performance impact of changes"
|
||||
|
||||
# Documentation consistency
|
||||
droid exec "Verify all functions have docstrings" --auto low
|
||||
```
|
||||
|
||||
### Test Generation
|
||||
```bash
|
||||
# Unit tests for specific module
|
||||
claude -p "Generate comprehensive unit tests for auth.py using pytest"
|
||||
|
||||
# Integration tests
|
||||
codex exec --full-auto "Create API integration tests with realistic data"
|
||||
|
||||
# Test coverage analysis
|
||||
qwen -p "Analyze test coverage and suggest missing test cases"
|
||||
```
|
||||
|
||||
### Documentation Automation
|
||||
```bash
|
||||
# API documentation
|
||||
find src/ -name "*.py" | gemini -p "Generate OpenAPI specification"
|
||||
|
||||
# README generation
|
||||
claude -p "Create comprehensive README with setup, usage, and examples"
|
||||
|
||||
# Changelog from commits
|
||||
git log --oneline | qwen -p "Generate changelog from commit history"
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
**GitHub Actions**
|
||||
```yaml
|
||||
- name: AI Code Review
|
||||
run: |
|
||||
git diff origin/main...HEAD | claude -p "Review for security and performance issues"
|
||||
```
|
||||
|
||||
**GitLab CI**
|
||||
```yaml
|
||||
script:
|
||||
- gemini -p "Generate test suite for new features" --output-format json > test_plan.json
|
||||
```
|
||||
|
||||
### Pre-commit Hooks
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# .git/hooks/pre-commit
|
||||
git diff --cached | claude -p "Check staged changes for obvious bugs"
|
||||
if [ $? -ne 0 ]; then exit 1; fi
|
||||
```
|
||||
|
||||
### Monitoring and Alerts
|
||||
```bash
|
||||
# Daily code quality report
|
||||
claude -p "Generate daily code quality report" | mail -s "Code Quality" team@example.com
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Security
|
||||
- Never use `--yolo` or equivalent flags in production environments
|
||||
- Validate AI-generated code before deployment
|
||||
- Use read-only mode for security-sensitive analysis
|
||||
- Implement human review for high-risk changes
|
||||
|
||||
### Performance
|
||||
- Limit the scope of analysis (specific files vs entire codebase)
|
||||
- Use structured output formats for programmatic processing
|
||||
- Cache results when appropriate
|
||||
- Monitor API usage and costs
|
||||
|
||||
### Reliability
|
||||
- Include fallback mechanisms for AI agent failures
|
||||
- Validate generated code with linters and tests
|
||||
- Use specific, well-defined prompts for consistent results
|
||||
- Implement retry logic for network issues
|
||||
|
||||
### Error Handling
|
||||
```bash
|
||||
# Robust script pattern
|
||||
if ! claude -p "Generate tests" > tests.py; then
|
||||
echo "AI generation failed, using fallback"
|
||||
cp fallback_tests.py tests.py
|
||||
fi
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Agent not found**: Ensure CLI tools are installed and in PATH
|
||||
```bash
|
||||
which claude codex gemini opencode qwen droid
|
||||
```
|
||||
|
||||
**Authentication errors**: Verify API keys and tokens
|
||||
```bash
|
||||
claude auth status
|
||||
codex auth verify
|
||||
```
|
||||
|
||||
**Permission denied**: Check file permissions and working directory
|
||||
```bash
|
||||
ls -la
|
||||
pwd
|
||||
```
|
||||
|
||||
**Context limit exceeded**: Reduce analysis scope or use specific files
|
||||
```bash
|
||||
# Instead of entire codebase
|
||||
claude -p "Analyze main.py only"
|
||||
|
||||
# Or use specific patterns
|
||||
find src/ -name "*.py" -maxdepth 2 | claude -p "Review these files"
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
Most agents support verbose output:
|
||||
```bash
|
||||
claude --verbose -p "Debug prompt"
|
||||
codex exec --debug "Debug task"
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
### references/
|
||||
|
||||
**agent-specific-commands.md** - Detailed command documentation for all six CLI agents including flags, options, and specific usage patterns. Load this when you need comprehensive syntax reference for a particular agent.
|
||||
|
||||
**use-case-examples.md** - Practical examples for CI/CD pipelines, shell scripts, and automation workflows. Load this when implementing specific automation scenarios or need concrete implementation patterns.
|
||||
|
||||
### scripts/
|
||||
|
||||
**validate-agent-setup.py** - Optional helper script to verify agent installations, API authentication, and basic functionality. Execute this to check if the required CLI agents are properly configured before using them in automation.
|
||||
|
||||
---
|
||||
|
||||
**References contain detailed command documentation and practical examples that complement this guide.**
|
||||
Reference in New Issue
Block a user