abk_env Developer Environment Setup

Automated developer environment setup and management for macOS and Linux systems. Provides JSON-based tool installation, shell configuration, git workflow automation, and centralized Claude environment management.

What This Skill Does

This skill helps you work with the `abk_env` repository - a comprehensive developer environment setup system that:

Instructions

When working with this repository, follow these guidelines:

1. Understanding the Architecture

**Core Components:**

**Claude Environment System:**

2. Common Development Tasks

**Testing Installation:**

```bash

./install.sh # Install minimal toolset

./install.sh tools_abk.json # Install ABK's favorite tools

./install.sh tools_python.json # Install Python tools

./test_install.sh # Validate installation

```

**Managing Tools:**

```bash

./uninstall.sh tools_abk.json # Remove specific package

./test_uninstall.sh # Test uninstall process

```

**Version Management:**

```bash

./unixBin/setGitAliases.sh # Setup git aliases

git rel-patch # Trigger patch release (x.y.Z)

git rel-minor # Trigger minor release (x.Y.0)

git rel-major # Trigger major release (X.0.0)

```

**Claude Environment:**

```bash

./unixBin/setClaudeEnv.sh # Setup centralized Claude env

./unixBin/resetClaudeEnv.sh # Reset to original state

```

3. Working with JSON Configuration Files

When modifying `tools_*.json` files:

**Structure:**

```json

{

"macOS": {

"description": "Tool description",

"supported_versions": { "macOS": ["13", "14", "15"] },

"update_packages": ["brew update", "brew upgrade"],

"tools": {

"check": { "toolname": ["command -v toolname"] },

"install": { "toolname": ["brew install toolname"] },

"uninstall": { "toolname": ["brew uninstall toolname"] }

},

"apps": { /* GUI applications */ },

"fonts": { /* Font installations */ }

},

"linux": { /* Linux-specific config */ }

}

```

**Key Points:**

4. Adding New Templates

When creating new Claude templates in `unixBin/env/claude/templates/`:

**Code Templates:**

**Configuration Templates:**

5. Release Workflow

**Automated Testing & Release:**

1. Make changes and commit to feature branch

2. Merge to main branch

3. Run `git rel-patch` (or `rel-minor`/`rel-major`)

4. Pipeline automatically:

- Runs tests on macOS (13, 14, 15) and Ubuntu (22.04, 24.04)

- Tests bash and zsh shells

- Validates install/uninstall operations

- If tests pass: bumps VERSION, creates release tag

- If tests fail: cleans up temp tags, no release created

**Release Tag Handling:**

6. Claude Environment Security Model

**Git-Controlled (Safe to Commit):**

**Generated Locally (Never Commit):**

**Environment Variable Sources:**

7. Testing Guidelines

**Before Committing:**

**Validation Checks:**

8. File Organization

**Key Directories:**

Important Constraints

1. **Never commit secrets** - Use environment variables and templates

2. **Test on target platforms** - Both macOS and Linux support required

3. **Preserve user data** - Setup scripts backup existing configurations

4. **Follow semantic versioning** - Use correct release type for changes

5. **Pipeline-only scripts** - Don't run `handle_release_tags.sh` manually

6. **JSON validation** - Always validate JSON syntax before committing

7. **Shell compatibility** - Support both bash and zsh shells

Example Usage

Adding a New Tool to Configuration

```bash

1. Edit the appropriate JSON file

vim tools_abk.json

2. Add tool definition for both platforms

{

"macOS": {

"tools": {

"check": { "newtool": ["command -v newtool"] },

"install": { "newtool": ["brew install newtool"] },

"uninstall": { "newtool": ["brew uninstall newtool"] }

}

},

"linux": {

"tools": {

"check": { "newtool": ["command -v newtool"] },

"install": { "newtool": ["sudo apt-get install -y newtool"] },

"uninstall": { "newtool": ["sudo apt-get remove -y newtool"] }

}

}

}

3. Test installation

./install.sh tools_abk.json

./test_install.sh tools_abk

4. Commit and release

git add tools_abk.json

git commit -m "Add newtool to ABK toolset"

git push origin main

git rel-minor # New feature = minor version bump

```

Creating a Claude Configuration Template

```bash

1. Create template file

cat > unixBin/env/claude/config/service.template.json << 'EOF'

{

"service": {

"apiKey": "${SERVICE_API_KEY}",

"endpoint": "${SERVICE_ENDPOINT:-https://api.service.com}"

}

}

EOF

2. Set environment variables

export SERVICE_API_KEY="your-key-here"

export SERVICE_ENDPOINT="https://custom.endpoint.com"

3. Run setup to generate config

./unixBin/setClaudeEnv.sh

4. Verify generated config (with secrets)

cat ~/.claude/config/service.json

5. Commit only the template

git add unixBin/env/claude/config/service.template.json

git commit -m "Add service configuration template"

```

References