# reference-atomworks

> Reference AtomWorks documentation and source for code improvement

- Author: N283T
- Repository: N283T/dotfiles
- Version: 20260120222824
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/N283T/dotfiles
- Web: https://mule.run/skillshub/@@N283T/dotfiles~reference-atomworks:20260120222824

---

---
name: reference-atomworks
description: Reference AtomWorks documentation and source for code improvement
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
timeout: 120000
---

# AtomWorks Documentation Reference

Reference AtomWorks docs and source to improve code quality.

**Repository:** https://github.com/RosettaCommons/atomworks
**Ecosystem:** Python

## Prerequisites

- `curl` and `tar` for downloading
- `SKILL_ROOT` environment variable (set automatically by Claude Code to the skill directory)

## Setup: Download Source

### Step 1: Detect version in project

```bash
# Match 'atomworks' as a word boundary
VERSION=$(grep -oE '\batomworks[=<>~!]*[0-9]+\.[0-9]+(\.[0-9]+)?' pyproject.toml requirements*.txt setup.py 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)
echo "Detected: ${VERSION:-not found, will use 2.2.0}"
```

### Step 2: Download source (if not cached)

```bash
VERSION="${VERSION:-2.2.0}"
CACHE_DIR="${SKILL_ROOT}/assets/atomworks-${VERSION}"

if [[ ! -d "$CACHE_DIR" ]]; then
  echo "Downloading atomworks v${VERSION}..."
  mkdir -p "${SKILL_ROOT}/assets" || { echo "Failed to create assets directory"; exit 1; }

  # Download and extract (GitHub archives extract to atomworks-VERSION/)
  curl -sfL "https://github.com/RosettaCommons/atomworks/archive/refs/tags/v${VERSION}.tar.gz" | \
    tar -xz -C "${SKILL_ROOT}/assets" || { echo "Download/extract failed"; exit 1; }

  # Verify extraction succeeded
  if [[ ! -d "$CACHE_DIR" ]]; then
    echo "Error: Expected directory $CACHE_DIR not found after extraction"
    exit 1
  fi

  echo "Cached: $CACHE_DIR"
else
  echo "Using cached: $CACHE_DIR"
fi

export LIB_SRC="$CACHE_DIR"
```

### Step 3: Build Index (if not exists)

```bash
INDEX_FILE="${SKILL_ROOT}/assets/atomworks-${VERSION}.index.json"

if [[ ! -f "$INDEX_FILE" ]]; then
  echo "Building index for atomworks v${VERSION}..."
  uv run "${SKILL_ROOT}/../make-lib-skill/build_index.py" "$CACHE_DIR" "$VERSION" "$INDEX_FILE"
fi

export LIB_INDEX="$INDEX_FILE"
```

## Query Index

Find relevant files for a topic before diving into source code.

### Find by module/topic name

```bash
# List all indexed modules
jq '.modules | keys[]' "$LIB_INDEX"

# Find paths for a specific module
jq '.modules["atomworks"]' "$LIB_INDEX"

# Search modules by partial name
jq '.modules | to_entries[] | select(.key | contains("structure"))' "$LIB_INDEX"
```

### Find by keyword

```bash
# Search for keyword in index
jq '.keywords["atom"]' "$LIB_INDEX"

# Search keywords containing a term
jq '.keywords | to_entries[] | select(.key | contains("parse"))' "$LIB_INDEX"
```

### Find files with specific classes/functions

```bash
# Find files defining a class
jq '.files | to_entries[] | select(.value.classes[]? | contains("Structure"))' "$LIB_INDEX"

# Find files with specific function
jq '.files | to_entries[] | select(.value.functions[]? | contains("load"))' "$LIB_INDEX"
```

## Reference Priority

| Priority | Path | Description |
|----------|------|-------------|
| 1 | `docs/` | Documentation (concepts, examples) |
| 2 | `atomworks/` | Python source code |
| 3 | `tests/` | Test examples showing usage |
| 4 | `examples/` | Example scripts and notebooks |

## Key Files

### docs/ (Documentation)

Explore the docs directory to find:
- API reference
- Tutorials and guides
- Concepts and design documentation
- Usage examples

```bash
# List available documentation
ls -la ${LIB_SRC}/docs/
```

### atomworks/ (Source code)

Main source code directory:

```bash
# Find main modules
ls -la ${LIB_SRC}/atomworks/
```

### examples/ (Example code)

Example scripts and notebooks demonstrating usage:

```bash
# List examples
ls -la ${LIB_SRC}/examples/
```

## Workflow

### 1. Find atomworks usage in project

```bash
grep -r "from atomworks" --include="*.py" .
grep -r "import atomworks" --include="*.py" .
```

### 2. Identify what to improve

Common areas:
- Atomic structure manipulation
- Protein/molecular analysis
- Data processing workflows
- Performance optimization
- API usage patterns

### 3. Read relevant documentation

```bash
# Explore available docs
Glob ${LIB_SRC}/docs/**/*.md
Glob ${LIB_SRC}/docs/**/*.rst

# Read specific documentation
Read ${LIB_SRC}/docs/[relevant-file]
```

### 4. Reference source for details

```bash
# Check actual implementation
Glob ${LIB_SRC}/atomworks/**/*.py
Read ${LIB_SRC}/atomworks/[module].py
```

### 5. Review examples

```bash
# Check example usage
Glob ${LIB_SRC}/examples/**/*.py
Read ${LIB_SRC}/examples/[example-file].py
```

## Output Format

```markdown
## Current Implementation
[Code snippet from project]

## AtomWorks Documentation (v${VERSION})
[Relevant info from docs - cite file path]

## Suggested Improvement
[Proposed changes]

## Benefits
- [Benefit 1]
- [Benefit 2]
```

## Usage

```
/reference-atomworks                   # Interactive
/reference-atomworks [specific topic]  # Focus on specific area
```

## Cache Management

```bash
# List cached versions
ls -la ${SKILL_ROOT}/assets/

# Remove old versions
rm -rf ${SKILL_ROOT}/assets/atomworks-x.y.z
```