swe-cli-skills

man pages for machines 🤖

Your agent knows the commands. We teach it the workflows.

swe-cli-skills is an open-source skill that gives AI coding agents senior-engineer-level CLI expertise. It covers 23 CLIs across 9 categories — not just flag syntax, but operational workflows, safety guardrails, gotchas, error recovery, and composition patterns.

One skill. Twenty-three CLIs. Every coding agent.

⚡ Install in 30 Seconds

npx (skills CLI)

npx skills add SylphAI-Inc/swe-cli-skills

Downloads and configures the skill for your AI agent. Works with AdaL, Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Windsurf, and more.

AdaL Plugin Marketplace

# Add the marketplace (one-time)
/plugin marketplace add SylphAI-Inc/swe-cli-skills

# Install the skill
/plugin install swe-cli-skills@swe-cli-skills

Manual Install (per agent)

# Project-level (recommended)
git clone https://github.com/SylphAI-Inc/swe-cli-skills.git .adal/skills/swe-cli-skills

# Personal (available in all projects)
git clone https://github.com/SylphAI-Inc/swe-cli-skills.git ~/.adal/skills/swe-cli-skills

cd your-project
git clone https://github.com/SylphAI-Inc/swe-cli-skills.git .claude/skills/swe-cli-skills

git clone https://github.com/SylphAI-Inc/swe-cli-skills.git .codex/skills/swe-cli-skills

git clone https://github.com/SylphAI-Inc/swe-cli-skills.git .gemini/skills/swe-cli-skills

git clone https://github.com/SylphAI-Inc/swe-cli-skills.git .github/skills/swe-cli-skills

git clone https://github.com/SylphAI-Inc/swe-cli-skills.git <agent-skills-dir>/swe-cli-skills

🎯 Why This Exists

AI coding agents generate CLI commands that look right but fail in production:

# Your agent generates this (WRONG):
aws s3 sync . s3://bucket --include "*.json" --exclude "*"
# Syncs NOTHING — filters are applied left-to-right

# With swe-cli-skills loaded, it generates this (CORRECT):
aws s3 sync . s3://bucket --exclude "*" --include "*.json"

# Your agent runs this (DANGEROUS):
terraform import aws_s3_bucket.logs my-app-logs
# No state backup, no lock, no plan after — drift goes undetected

# With swe-cli-skills loaded:
terraform state pull > backup-$(date +%Y%m%d).tfstate
terraform import -lock=true aws_s3_bucket.logs my-app-logs
terraform plan  # Always verify after import

# Your agent tries this (HANGS):
git rebase -i HEAD~3
# No TTY available — agent is stuck forever

# With swe-cli-skills loaded:
GIT_SEQUENCE_EDITOR="sed -i 's/pick/squash/2'" git rebase -i HEAD~3

The pattern: Models know CLI syntax. They don't know CLI wisdom.

📚 What's Included

One SKILL.md entry point → 9 categories → 23 expert CLI guides:

☁️ Cloud

🏗️ Infrastructure as Code

🐳 Containers & Orchestration

🔀 Git & Version Control

🛠️ Dev Tools

📦 Package Managers

🗄️ Databases

🚀 Platforms & Services

Each guide follows a consistent structure:

1. Setup & Auth — Installation and credential configuration
2. Core Workflows — The 20% of commands covering 80% of usage
3. Flag Gotchas — Ordering traps, version quirks, surprising defaults
4. Error Patterns — Real error messages → real fixes
5. Anti-Patterns — "Never do X because Y" with safe alternatives
6. Composability — How to pipe this CLI with others (aws → jq → xargs)
7. Agent Constraints — Non-interactive alternatives, TTY workarounds

🧠 How It Works

This repo is a single skill following the Agent Skills spec:

swe-cli-skills/
├── SKILL.md                      ← Agent reads this first (index + quick reference)
└── skills/
    ├── cloud/
    │   ├── INDEX.md              ← Category index
    │   ├── aws.md
    │   ├── gcloud.md
    │   └── azure.md
    ├── iac/
    │   ├── INDEX.md
    │   └── terraform.md
    ├── containers/
    │   ├── INDEX.md
    │   ├── docker.md
    │   ├── kubectl.md
    │   └── helm.md
    ├── git-vcs/
    │   ├── INDEX.md
    │   ├── git.md
    │   └── gh.md
    ├── dev-tools/
    │   ├── INDEX.md
    │   ├── jq.md
    │   ├── curl.md
    │   ├── ssh.md
    │   ├── sed.md
    │   └── make.md
    ├── package-managers/
    │   ├── INDEX.md
    │   ├── npm.md
    │   └── pip-uv.md
    ├── databases/
    │   ├── INDEX.md
    │   ├── psql.md
    │   └── redis.md
    └── platforms/
        ├── INDEX.md
        ├── stripe.md
        ├── sentry.md
        ├── vercel.md
        ├── firebase.md
        └── fly.md

1. Your agent sees swe-cli-skills in its skill index (name + description)
2. When a CLI task comes up, it reads SKILL.md (lightweight — just the index)
3. It loads the specific CLI guide it needs (e.g., skills/iac/terraform.md)
4. It executes with expert-level knowledge

Token-efficient by design — the agent only loads one guide (~200-400 lines) instead of the entire library.

🔥 Critical Gotchas Cheat Sheet

The highest-impact mistakes agents make — a taste of what's inside:

🤝 Compatible Agents

Works with any agent that supports the SKILL.md standard:

• AdaL — Project/personal/plugin skills
• Claude Code — Plugin marketplace
• OpenAI Codex — Skills directory
• Gemini CLI — Agent skills
• GitHub Copilot — .github/skills
• Cursor — Custom instructions
• Windsurf — Agent skills
• Aider — Convention files
• OpenCode — Skills support
• Any agent that reads markdown instruction files

📖 Philosophy

1. Workflows over reference — "Here's how to deploy safely" not "here's every flag"
2. Opinionated — We encode senior engineer judgment, not neutral docs
3. Agent-first, human-readable — Written for LLMs to parse, useful for humans too
4. Composability-aware — Skills show how CLIs work together
5. Version-tagged — Each guide declares which CLI version it targets
6. Battle-tested patterns — Real gotchas from real production incidents

🗺️ Roadmap

• v0.1 — Core 10 CLIs (aws, terraform, docker, kubectl, helm, git, gh, jq, curl, ssh)
• v0.2 — 16 CLIs with category sub-indexes (gcloud, azure, npm, pip/uv, psql, redis-cli)
• v0.3 — 23 CLIs with platforms & expanded dev-tools (stripe, sentry, vercel, firebase, fly.io, sed, make)
• v0.4 — rsync, mysql, mongo, yarn/pnpm, cargo, go, poetry, openssl
• v1.0 — 30+ CLIs, community contributions, CI validation
• Future — Version-specific skill variants, auto-update from changelogs

🤲 Contributing

Every skill you add helps thousands of AI agents operate more safely and effectively.

See CONTRIBUTING.md for the full guide.

Quick version:

1. Create skills/<category>/your-cli.md following the guide structure
2. Add an entry to the category INDEX.md
3. Add an entry to SKILL.md and this README
4. Open a PR

What makes a great skill: Opinionated workflows, real gotchas you've been burned by, actual error messages with actual fixes, and non-interactive alternatives for every interactive command.

📄 License

MIT — use these skills in any project, commercial or open-source.

⭐ Star this repo if your agent has ever kubectl apply'd to the wrong cluster.

Built by SylphAI — the team behind AdaL