🤖 Claude Agent Skills Stack

Self-contained skills for autonomous AI agents Production-ready tools, templates, and validators for Docker and Kubernetes

Installation • Skills • Quick Start • Architecture • Development

🔄 Breaking Change — helm-chart-generator renamed to helm-bjw-s-chart (v3.0.0)

Starting with release v3.0.0, the skill formerly known as helm-chart-generator is now called helm-bjw-s-chart to make its scope explicit (it targets the bjw-s common library, not generic Helm charts).

What changes for you:

Migration:

# 1. Remove the old skill
npx skills remove helm-chart-generator -g -y

# 2. Install the new one (see Installation section below)
npx skills add obeone/claude-skills -g --skill helm-bjw-s-chart -y

Any automation, doc, or agent still pointing to the old URL or name will break at the first install/refresh after v3.0.0 ships.

📦 Installation

Recommended — skills CLI

The skills CLI resolves any GitHub repo and wires the bundles into the right agent directories (Claude Code, Cursor, …). Run it via npx — no global Node install required.

# Interactive — pick scope and agents
npx skills add obeone/claude-skills

# All skills, user-global (~/.claude/skills)
npx skills add obeone/claude-skills -g --all

# All skills, current project (./.claude/skills)
npx skills add obeone/claude-skills --all

# A single skill (project-scoped; add -g for global)
npx skills add obeone/claude-skills --skill dockerfile-best-practices -y

# List available skills in the repo without installing
npx skills add obeone/claude-skills -l

Update later with npx skills update, remove with npx skills remove, inspect with npx skills list. Full options: npx skills -h.

Claude.ai (Web)

1. Download the .skill bundles from Releases
2. Go to Settings → Skills
3. Click Upload skill and select each .skill file

Manual — release bundle (fallback)

If you can't run Node on the host:

mkdir -p ~/.claude/skills

for skill in dockerfile-best-practices helm-bjw-s-chart automode-config; do
  curl -L "https://github.com/obeone/claude-skills/releases/latest/download/${skill}.skill" \
    -o /tmp/skill.zip && unzip -o /tmp/skill.zip -d ~/.claude/skills/
done

Swap ~/.claude/skills/ for .claude/skills/ for a project-scoped install.

From Source

git clone https://github.com/obeone/claude-skills.git
cp -r claude-skills/skills/dockerfile-best-practices ~/.claude/skills/
cp -r claude-skills/skills/helm-bjw-s-chart ~/.claude/skills/
cp -r claude-skills/skills/automode-config ~/.claude/skills/

Other Platforms

The skills CLI auto-detects supported agents; pass --agent <name> to target a specific one (e.g. --agent cursor). For unsupported agents, extract the .skill bundle into the agent's skills directory.

How it works: Skills are packaged using Skill Pack on every release. The action creates .skill bundles (ZIP archives) and uploads them to GitHub releases.

📖 Overview

This repository provides modular skills for Claude and other AI agents. Each skill is a self-contained bundle that includes:

• 📋 SKILL.md — Main entry point with decision trees and workflows
• 🔧 Scripts — Python validators and analyzers
• 📚 References — Deep-dive documentation and best practices
• 📦 Assets — Templates and boilerplate code

Skills are designed to be installed once, used everywhere — whether you're optimizing a Dockerfile, generating Helm charts, or setting up CI/CD pipelines.

⚡ Quick Start

Using with Claude Code

Skills are automatically discovered when you run Claude Code in this repository. Simply ask:

"Create a Dockerfile for my Python FastAPI application"
"Generate a Helm chart for this container image"
"Analyze my Dockerfile for best practices"
"Set up Claude Code autoMode for this project"

Manual Usage

# Analyze a Dockerfile (uv reads PEP 723 metadata in the script header)
uv run skills/dockerfile-best-practices/scripts/analyze_dockerfile.py ./Dockerfile

# Analyze a Docker Compose file
uv run skills/dockerfile-best-practices/scripts/analyze_compose.py ./compose.yaml

# Validate a Helm chart
uv run skills/helm-bjw-s-chart/scripts/validate_chart.py ./my-chart/

# Inspect Claude Code autoMode state for the current project
uv run skills/automode-config/scripts/inspect_automode.py

# Scan the project for autoMode adoption candidates
uv run skills/automode-config/scripts/scan_project.py

🎯 Available Skills

🧩 Architecture

skills/<skill-name>/
├── SKILL.md              # Entry point with YAML front-matter
│                         # Contains: name, description
│
├── scripts/              # Python validation tools
│   ├── analyze_*.py      # Static analyzers — PEP 723 inline deps
│   └── validate_*.py     # Structure validators — PEP 723 inline deps
│
├── assets/               # Templates and static files
│   └── templates/        # Boilerplate code
│
└── references/           # Documentation and guides
    ├── best-practices.md # Comprehensive checklists
    ├── patterns.md       # Common patterns and examples
    └── *.md              # Topic-specific guides

Design Principles

📘 Usage

Skill Installation

Skills can be packaged and distributed using the Skill Pack action:

# Skills are automatically packed on release
git tag v1.0.0
git push origin v1.0.0

CI/CD Integration

This repository includes GitHub Actions workflows:

Python Scripts

Every entry-point script declares its dependencies inline as a PEP 723 header. uv run path/to/script.py resolves and caches them automatically — no pip install step.

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run a script (uv reads the script's PEP 723 header and prepares the env)
uv run skills/dockerfile-best-practices/scripts/analyze_dockerfile.py ./Dockerfile

🔍 Key Features by Skill

dockerfile-best-practices

• Language templates: Python/uv, Node.js, Go, Rust, PHP, Debian
• Security patterns: Non-root users (UID/GID >10000), secret mounts, SBOM and provenance attestations
• Performance optimization: Cache mounts, multi-stage builds, layer ordering
• Static analyzer: 30+ rules, including the defects a green build never reveals (a --chown silently discarded to root, a healthcheck calling a binary the image does not ship)
• Compose support: Modern V2 practices (no version: field, runtime hardening, container_name: only where you will never --scale)
• Linting, ours and everyone else's: where docker build --check, hadolint, DCLint and this repo's own analyzers overlap, and where each one is the only tool that catches a given defect
• Compose file naming: all four names Compose V2 accepts are valid, so the skill matches whatever the project already uses, asks once when there is no precedent, and remembers the answer

helm-bjw-s-chart

• bjw-s common library: app-template v4+ patterns
• Complete chart structure: Chart.yaml, values.yaml, common.yaml, NOTES.txt
• Deployment patterns: Single container, sidecars, init containers, multi-controller
• Best practices: Resource limits, security contexts, health probes
• Chart validator: Verifies structure and bjw-s compatibility

automode-config

• Four-bucket model: allow / ask / deny / hard_deny with hard_deny round-trip
• Critique-gated writes: claude auto-mode critique exit code is the contract; raw output archived per run
• Atomic + reversible: per-file flock, O_EXCL write, five rolling backups, sha256 commit predicate
• Capability auto-detection: silently swaps ~/.claude/settings.json when the CLI lacks --settings
• Recovery: --repair reclaims stale flocks and restores .preview-orig orphans
• Requires Claude Code 2.1.136+

🔨 Development

Repository Structure

.
├── README.md             # This file
├── CLAUDE.md             # Claude Code configuration
├── AGENTS.md             # Agent guidelines
├── .github/
│   └── workflows/        # CI/CD automation
└── skills/
    ├── dockerfile-best-practices/
    ├── helm-bjw-s-chart/
    └── automode-config/

Mandatory Requirements

1. SKILL.md YAML front-matter: Every skill must have name, description, and metadata.version:

   ---
   name: my-skill
   description: "Skill description"
   metadata:
     version: "1.0.0"
   ---
   

2. POSIX compliance: All files must end with newline (\n) and use LF line endings
3. Python via uv: Use uv for dependency management

Adding a New Skill

1. Create skills/<skill-name>/SKILL.md with required front-matter (see format above)
2. Add scripts/ with validators and analyzers
3. Add references/ with deep-dive documentation
4. Add assets/ with templates if needed
5. Submit a PR — the validate-skills workflow will verify structure

📄 License

MIT License — see LICENSE for details.

🙏 Credits

• bjw-s common library for Helm chart patterns
• astral-sh/uv for Python package management
• Docker BuildKit for modern build features

Built with 🤖 by autonomous agents, for autonomous agents