infrastructure-skill-builder

インフラストラクチャスキルビルダー

インフラストラクチャのドキュメントを、強力で再利用可能な Claude Code スキルに変換します。

概要

インフラストラクチャに関する知識は、次のような場所に散在していることがよくあります。

• README ファイル
• ランブックや Wiki ページ
• 設定ファイル
• トラブルシューティングガイド
• チームの Slack／Discord の履歴
• シニアエンジニアの頭の中にあるメンタルモデル

このスキルを使うと、そうした知識を Claude Code スキルとして体系的に記録でき、次のことに役立ちます。

• オンボーディングの迅速化
• 運用の一貫性向上
• 災害復旧
• 知識の保存
• チームの拡大

使用する場面

次のような場合にこのスキルを使用してください。

• 複雑なインフラストラクチャ構成を文書化するとき
• 運用チーム向けのランブックを作成するとき
• 新しいチームメンバーのインフラストラクチャに関するオンボーディングを行うとき
• チームに変更が生じる前に専門知識を保存するとき
• インフラストラクチャ運用を標準化するとき
• 組織内のインフラストラクチャライブラリを構築するとき
• 手動運用から自動運用へ移行するとき

スキルの抽出プロセス

ステップ 1：インフラストラクチャの領域を特定する

一般的な領域：

• コンテナオーケストレーション：Docker、Kubernetes、Proxmox LXC
• クラウドプラットフォーム：AWS、GCP、Azure、DigitalOcean
• データベース：PostgreSQL、MongoDB、Redis、MySQL
• Web サーバー：Nginx、Apache、Caddy、Traefik
• モニタリング：Prometheus、Grafana、ELK Stack
• CI/CD：Jenkins、GitLab CI、GitHub Actions
• ネットワーク：VPN、ロードバランサー、DNS、ファイアウォール
• ストレージ：S3、MinIO、NFS、Ceph
• セキュリティ：認証、SSL/TLS、ファイアウォール

ステップ 2：主要な操作を抽出する

各領域について、次の内容を文書化します。

1. セットアップ／プロビジョニング：新しいインスタンスの作成方法
2. 設定：さまざまなユースケースに合わせた設定方法
3. 運用：日常的な管理タスク
4. トラブルシューティング：よくある問題と解決方法
5. スケーリング：スケールアップ／ダウンの方法
6. バックアップ／復旧：災害復旧の手順
7. モニタリング：ヘルスチェックとアラート
8. セキュリティ：セキュリティのベストプラクティス

インフラストラクチャスキルのテンプレート

---
name: [infrastructure-component]-manager
description: Expert guidance for [component] management, provisioning, troubleshooting, and operations
license: MIT
tags: [infrastructure, [component], operations, troubleshooting]
---

# [Component] Manager

Expert knowledge for managing [component] infrastructure.

## Authentication & Access

### Access Methods
```bash
# How to access the infrastructure component
ssh user@host
# or
kubectl config use-context cluster-name

認証情報と設定

• 認証情報の保存場所
• アクセスの設定方法
• よくある認証の問題

アーキテクチャの概要

コンポーネントのトポロジー

• コンポーネントの構成
• ネットワークトポロジー
• リソース割り当て
• 冗長化の設定

主なリソース

• リソース 1：用途と仕様
• リソース 2：用途と仕様
• リソース 3：用途と仕様

一般的な操作

操作 1：[例：新しいインスタンスの作成]

# Step-by-step commands
command1 --flags
command2 --flags

# Verification
verify-command

操作 2：[例：設定の更新]

# Commands and explanations

操作 3：[例：リソースのスケーリング]

# Commands and explanations

モニタリングとヘルスチェック

システムステータスの確認

# Health check commands
status-command

# Expected output
# What healthy output looks like

主なメトリクス

• メトリクス 1：意味、正常な範囲
• メトリクス 2：意味、正常な範囲
• メトリクス 3：意味、正常な範囲

トラブルシューティング

問題 1：[よくある問題]

症状：確認できる現象 原因：発生する理由 解決方法：段階的な解決手順

# Fix commands

問題 2：[別の問題]

症状： 原因： 解決方法：

# Fix commands

バックアップと復旧

バックアップ手順

# How to backup
backup-command

# Verification
verify-backup

復旧手順

# How to restore
restore-command

# Verification
verify-restore

セキュリティのベストプラクティス

• セキュリティ対策 1
• セキュリティ対策 2
• セキュリティ対策 3

クイックリファレンス

タスク	コマンド
タスク 1	command1
タスク 2	command2
タスク 3	command3

追加リソース

• 公式ドキュメントへのリンク
• 関連スキル
• 外部資料

## Real-World Example: Proxmox Skill

Based on the proxmox-auth skill in this repository:

### Extracted Knowledge

**From**: Proxmox VE cluster documentation + operational experience

**Structured as**:
1. **Authentication**: SSH access patterns, node IPs
2. **Architecture**: Cluster topology (2 nodes, resources)
3. **Operations**: Container/VM management commands
4. **Troubleshooting**: Common errors and fixes
5. **Networking**: Bridge configuration, IP management
6. **GPU Passthrough**: Special container configurations

**Result**: Comprehensive skill covering:
- Quick access to any node
- Container lifecycle management
- GPU-accelerated containers
- Network troubleshooting
- Backup procedures
- Common gotchas and solutions

## Extraction Scripts

### Extract from Runbooks

```bash
#!/bin/bash
# extract-from-runbook.sh - Convert runbook to skill

RUNBOOK_FILE="$1"
SKILL_NAME="$2"

if [ -z "$RUNBOOK_FILE" ] || [ -z "$SKILL_NAME" ]; then
    echo "Usage: $0 <runbook.md> <skill-name>"
    exit 1
fi

SKILL_DIR="skills/$SKILL_NAME"
mkdir -p "$SKILL_DIR"

# Extract sections from runbook
cat > "$SKILL_DIR/SKILL.md" << EOF
---
name: $SKILL_NAME
description: $(head -5 "$RUNBOOK_FILE" | grep -v "^#" | head -1 | xargs)
license: MIT
extracted-from: $RUNBOOK_FILE
---

# ${SKILL_NAME^}

$(cat "$RUNBOOK_FILE")

---

**Note**: This skill was auto-extracted from runbook documentation.
Review and refine before use.
EOF

echo "✓ Created skill: $SKILL_DIR/SKILL.md"
echo "Review and edit to add:"
echo "  - Metadata and tags"
echo "  - Troubleshooting section"
echo "  - Quick reference"
echo "  - Examples"

Docker Compose から抽出する

#!/bin/bash
# docker-compose-to-skill.sh - Extract skill from docker-compose.yaml

COMPOSE_FILE="${1:-docker-compose.yaml}"
PROJECT_NAME=$(basename $(pwd))

SKILL_DIR="skills/docker-$PROJECT_NAME"
mkdir -p "$SKILL_DIR"

# Extract services
SERVICES=$(yq eval '.services | keys | .[]' "$COMPOSE_FILE")

cat > "$SKILL_DIR/SKILL.md" << EOF
---
name: docker-$PROJECT_NAME
description: Docker Compose configuration and management for $PROJECT_NAME
license: MIT
---

# Docker $PROJECT_NAME

Manage Docker Compose stack for $PROJECT_NAME.

## Services

$(yq eval '.services | to_entries | .[] | "### " + .key + "\n" + (.value.image // "custom") + "\n"' "$COMPOSE_FILE")

## Quick Start

\`\`\`bash
# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Stop all services
docker-compose down
\`\`\`

## Service Details

### Ports

$(yq eval '.services | to_entries | .[] | select(.value.ports) | "- **" + .key + "**: " + (.value.ports | join(", "))' "$COMPOSE_FILE")

### Volumes

$(yq eval '.services | to_entries | .[] | select(.value.volumes) | "- **" + .key + "**: " + (.value.volumes | join(", "))' "$COMPOSE_FILE")

## Configuration

See \`$COMPOSE_FILE\` for full configuration.

## Common Operations

### Restart Service

\`\`\`bash
docker-compose restart SERVICE_NAME
\`\`\`

### Update Service

\`\`\`bash
docker-compose pull SERVICE_NAME
docker-compose up -d SERVICE_NAME
\`\`\`

### View Service Logs

\`\`\`bash
docker-compose logs -f SERVICE_NAME
\`\`\`

## Troubleshooting

### Service Won't Start

1. Check logs: \`docker-compose logs SERVICE_NAME\`
2. Verify ports not in use: \`netstat -tulpn | grep PORT\`
3. Check disk space: \`df -h\`

### Network Issues

\`\`\`bash
# Recreate network
docker-compose down
docker network prune
docker-compose up -d
\`\`\`
EOF

echo "✓ Created skill from docker-compose.yaml"

Kubernetes マニフェストから抽出する

#!/bin/bash
# k8s-to-skill.sh - Extract skill from Kubernetes manifests

K8S_DIR="${1:-.}"
APP_NAME="${2:-$(basename $(pwd))}"

SKILL_DIR="skills/k8s-$APP_NAME"
mkdir -p "$SKILL_DIR"

cat > "$SKILL_DIR/SKILL.md" << EOF
---
name: k8s-$APP_NAME
description: Kubernetes deployment and management for $APP_NAME
license: MIT
---

# Kubernetes $APP_NAME

Manage Kubernetes resources for $APP_NAME.

## Resources

$(find "$K8S_DIR" -name "*.yaml" -o -name "*.yml" | while read file; do
    KIND=$(yq eval '.kind' "$file" 2>/dev/null)
    NAME=$(yq eval '.metadata.name' "$file" 2>/dev/null)
    echo "- **$KIND**: $NAME ($(basename $file))"
done)

## Deployment

### Apply All Resources

\`\`\`bash
kubectl apply -f $K8S_DIR/
\`\`\`

### Check Status

\`\`\`bash
# Pods
kubectl get pods -l app=$APP_NAME

# Services
kubectl get svc -l app=$APP_NAME

# Deployments
kubectl get deploy -l app=$APP_NAME
\`\`\`

## Common Operations

### Scale Deployment

\`\`\`bash
kubectl scale deployment $APP_NAME --replicas=3
\`\`\`

### Update Image

\`\`\`bash
kubectl set image deployment/$APP_NAME container=new-image:tag
\`\`\`

### View Logs

\`\`\`bash
kubectl logs -f deployment/$APP_NAME
\`\`\`

### Port Forward

\`\`\`bash
kubectl port-forward svc/$APP_NAME 8080:80
\`\`\`

## Troubleshooting

### Pod Not Starting

\`\`\`bash
# Check pod events
kubectl describe pod POD_NAME

# Check logs
kubectl logs POD_NAME

# Previous instance logs
kubectl logs POD_NAME --previous
\`\`\`

### Service Not Reachable

\`\`\`bash
# Check endpoints
kubectl get endpoints $APP_NAME

# Check service
kubectl describe svc $APP_NAME

# Test from another pod
kubectl run -it --rm debug --image=busybox --restart=Never -- wget -O- http://$APP_NAME
\`\`\`

## Quick Reference

| Task | Command |
|------|---------|
| Apply | \`kubectl apply -f $K8S_DIR/\` |
| Status | \`kubectl get all -l app=$APP_NAME\` |
| Logs | \`kubectl logs -f deployment/$APP_NAME\` |
| Scale | \`kubectl scale deployment $APP_NAME --replicas=N\` |
| Delete | \`kubectl delete -f $K8S_DIR/\` |
EOF

echo "✓ Created Kubernetes skill"

記録するインフラストラクチャのパターン

パターン 1：SSH アクセスマトリックス

## SSH Access

| Host | IP | Purpose | Access |
|------|--------|---------|--------|
| node1 | 192.168.1.10 | Primary | `ssh node1` |
| node2 | 192.168.1.11 | Secondary | `ssh node2` |
| bastion | 203.0.113.5 | Jump host | `ssh -J bastion node1` |

パターン 2：サービスのポートマッピング

## Service Ports

| Service | Internal | External | Protocol |
|---------|----------|----------|----------|
| Web | 8080 | 80 | HTTP |
| API | 3000 | 443 | HTTPS |
| DB | 5432 | - | TCP |

パターン 3：設定ファイル

## Configuration Locations

### Application Config
- Path: `/etc/app/config.yaml`
- Format: YAML
- Requires restart: Yes

### Database Config
- Path: `/var/lib/postgres/postgresql.conf`
- Format: INI
- Requires restart: Yes

パターン 4：コマンドワークフロー

## Deployment Workflow

1. **Backup current state**
   ```bash
   ./backup.sh

2. 最新のコードを取得

   git pull origin main
   

3. アプリケーションをビルド

   docker build -t app:latest .
   

4. デプロイ

   docker-compose up -d
   

5. 検証

   curl http://localhost/health
   

## Best Practices

### ✅ DO

1. **Document assumptions** - What's required before operations
2. **Include verification** - How to verify each operation succeeded
3. **Add troubleshooting** - Common issues and fixes
4. **Show outputs** - Expected command outputs
5. **Link resources** - Related documentation and skills
6. **Version information** - Software versions, configurations
7. **Security notes** - Security implications of operations
8. **Update regularly** - Keep skills current with infrastructure

### ❌ DON'T

1. **Don't hardcode secrets** - Use placeholders or env vars
2. **Don't skip context** - Explain why, not just how
3. **Don't assume knowledge** - Explain terminology
4. **Don't omit edge cases** - Document special scenarios
5. **Don't forget cleanup** - Include teardown procedures
6. **Don't ignore dependencies** - Document prerequisites
7. **Don't skip testing** - Verify all commands work
8. **Don't leave TODO** - Complete all sections

## Quality Checklist

- [ ] Clear component description
- [ ] Authentication/access documented
- [ ] Architecture overview provided
- [ ] Common operations with examples
- [ ] Troubleshooting section complete
- [ ] Health checks documented
- [ ] Backup/recovery procedures
- [ ] Security considerations noted
- [ ] Quick reference table
- [ ] All commands tested
- [ ] No hardcoded secrets
- [ ] Links to resources

## Quick Start Workflow

```bash
# 1. Identify infrastructure component
COMPONENT="nginx-reverse-proxy"

# 2. Gather documentation
# - Collect README files
# - Export wiki pages
# - Capture team knowledge
# - Document current setup

# 3. Create skill structure
mkdir -p skills/$COMPONENT

# 4. Fill in template
# Use the Infrastructure Skill Template above

# 5. Test all commands
# Verify every command in skill works

# 6. Review and refine
# Have team review for completeness

# 7. Commit to repository
git add skills/$COMPONENT
git commit -m "docs: Add $COMPONENT infrastructure skill"

---

バージョン：1.0.0 作成者：proxmox-auth スキルパターンから収集 最終更新日：2025-11-18 ライセンス：MIT 基本原則：経験則を構造化され、検索可能で、実行可能なスキルに変換します。

このリポジトリの例

• proxmox-auth：Proxmox VE クラスター管理
• docker-*：Docker ベースのインフラストラクチャ
• cloudflare-*：Cloudflare インフラストラクチャサービス

インフラストラクチャのドキュメントを、今すぐスキルに変換しましょう！ 🏗️