Module Spec Generator

Module Spec Generator Skill

Purpose

This skill automatically generates comprehensive module specifications from code analysis, ensuring adherence to amplihack's brick philosophy and enabling effective module regeneration without breaking system connections.

When to Use This Skill

• Creating new modules: Generate specs before implementation to clarify requirements
• Documenting existing modules: Extract specifications from working code for future reference
• Module reviews: Verify specs accurately represent implemented contracts
• Refactoring decisions: Use specs to understand module boundaries and dependencies
• Knowledge preservation: Document expert patterns and design decisions

Core Philosophy: Bricks & Studs

Brick = Self-contained module with ONE clear responsibility Stud = Public contract (functions, API, data models) others connect to Regeneratable = Can be rebuilt from specification without breaking connections

A good spec enables rebuilding ANY module independently while preserving its connection points.

Specification Template

Every module specification includes these sections:

1. Module Overview

# [Module Name] Specification

## Purpose
One-sentence description of the module's core responsibility.

## Scope
What this module handles | What it explicitly does NOT handle

## Philosophy Alignment
How this module embodies brick principles and simplicity.

2. Public Contract (The "Studs")

## Public Interface

### Functions
- `function_name(param: Type) -> ReturnType`
  Brief description of what it does.

### Classes/Data Models
- `ClassName`
  - Fields: list with types
  - Key methods: list

### Constants/Enums
Important module-level constants and their purposes.

3. Dependencies

## Dependencies

### External Dependencies
- `library_name` (version): What it's used for

### Internal Dependencies
- `module_path`: How this module depends on it

### NO External Dependencies (Best Case)
Pure Python, standard library only.

4. Module Structure

## Module Structure

module_name/ ├── init.py # Public interface via all ├── core.py # Main implementation ├── models.py # Data models (if needed) ├── utils.py # Internal utilities ├── tests/ │ ├── init.py │ ├── test_core.py # Main functionality tests │ ├── test_models.py # Data model tests (if needed) │ └── fixtures/ │ └── sample_data.json └── examples/ └── basic_usage.py # Usage examples

5. Test Requirements

## Test Requirements

### Unit Tests
- Test 1: Purpose and what it verifies
- Test 2: ...

### Integration Tests (if applicable)
- Test 1: ...

### Coverage Goal
Target test coverage percentage (typically 85%+)

6. Example Usage

````

Example Usage

from module_name import PublicFunction, DataModel

# Usage example 1
result = PublicFunction(input_data)

# Usage example 2
model = DataModel(field1="value", field2=123)

## Step-by-Step Analysis Process

### Step 1: Understand the Module
1. Read all module files (focus on `__init__.py` and core implementations)
2. Identify the single core responsibility
3. Note architectural patterns used (classes, functions, mixins, etc.)

### Step 2: Extract Public Contract
1. List all exports in `__all__` or equivalent
2. Document function signatures with full type hints
3. Identify data structures (classes, NamedTuple, dataclass)
4. Extract constants and their meanings
5. Include docstrings for each public item

### Step 3: Map Dependencies
1. Scan imports at module level
2. Categorize:
   - Standard library (good - include version constraints)
   - External packages (list version requirements)
   - Internal modules (note the module path)
3. Identify circular dependencies (red flag)

### Step 4: Analyze Module Structure
1. Map file organization
2. Identify what goes in each file
3. Note test fixtures and examples

### Step 5: Identify Test Requirements
1. What behaviors MUST be tested
2. What edge cases exist
3. What integration points need coverage
4. Suggest coverage target

### Step 6: Generate Spec Document
1. Create Specs/[module-name].md
2. Fill in all sections using analysis
3. Include example code
4. Verify spec allows module regeneration

## Usage Examples

### Example 1: Generate Spec for New Module

User: I'm creating a new authentication module. Generate a spec that ensures it follows brick philosophy.

Claude:

1. Interviews user about module purpose, public functions, dependencies 2. Analyzes similar modules in codebase 3. Generates comprehensive spec with:

• Clear single responsibility
• Public contract defining studs
• Test requirements
• Example implementations

4. Saves to Specs/authentication.md

### Example 2: Document Existing Module

User: Generate a spec for the existing caching module.

Claude:

1. Analyzes .claude/tools/amplihack/caching/ directory 2. Extracts all exports 3. Documents public functions with signatures 4. Maps dependencies 5. Identifies test requirements 6. Creates Specs/caching.md 7. Offers to verify spec matches implementation

### Example 3: Verify Module Spec Accuracy

User: Check if the existing session management spec accurately describes the implementation.

Claude:

1. Reads Specs/session-management.md 2. Analyzes actual code in .claude/tools/amplihack/session/ 3. Compares:

• Public contract (functions, signatures)
• Dependencies listed
• Test coverage

4. Reports discrepancies 5. Suggests spec updates if needed

````

Analysis Checklist

Code Analysis

• [ ] Read all Python files in module
• [ ] Identify __all__ or equivalent public interface
• [ ] Extract all public function signatures
• [ ] Document all public classes with fields and methods
• [ ] List module-level constants
• [ ] Map all imports (external and internal)

Philosophy Verification

• [ ] Single clear responsibility
• [ ] No unnecessary abstractions
• [ ] Public interface clear and minimal
• [ ] Dependencies are justified
• [ ] No external dependencies (if possible)
• [ ] Patterns align with amplihack principles

Specification Quality

• [ ] Spec is complete and precise
• [ ] Code examples are accurate and working
• [ ] Test requirements are realistic
• [ ] Module structure is clear
• [ ] Someone could rebuild module from spec
• [ ] Regeneration preserves all connections

Template for Module Specs

# [Module Name] Specification

## Purpose
[Single sentence describing core responsibility]

## Scope
**Handles**: [What this module does]
**Does NOT handle**: [What is explicitly out of scope]

## Philosophy Alignment
- ✅ Ruthless Simplicity: [How it embodies this]
- ✅ Single Responsibility: [Core job]
- ✅ No External Dependencies: [True/False with reason]
- ✅ Regeneratable: [Yes, module can be rebuilt from this spec]

## Public Interface (The "Studs")

### Functions

def primary_function(param: Type) -> ReturnType: """Brief description.

Args: param: Description with constraints

Returns: Description of return value """ ````

Classes

class DataModel:
    """Brief description of responsibility.

    Attributes:
        field1 (Type): Description
        field2 (Type): Description
    """

Constants

• CONSTANT_NAME: Description and usage

Dependencies

External

None - pure Python standard library

Internal

• .models: Data structures
• .utils: Shared utilities

Module Structure

module_name/
├── __init__.py       # Exports via __all__
├── core.py          # Implementation
├── models.py        # Data models
├── utils.py         # Utilities
├── tests/
│   └── test_core.py
└── examples/
    └── usage.py

Test Requirements

Core Functionality Tests

• ✅ Test primary_function with valid input
• ✅ Test error handling with invalid input
• ✅ Test edge cases

Contract Verification

• ✅ All exported items in all work
• ✅ Type hints match actual behavior
• ✅ Return values match documentation

Coverage Target

85%+ line coverage

Example Usage

from module_name import primary_function, DataModel

# Basic usage
result = primary_function(input_data)

# Data model usage
model = DataModel(field1="value", field2=123)
print(model.field1)

Regeneration Notes

This module can be rebuilt from this specification while maintaining:

• ✅ Public contract (all "studs" preserved)
• ✅ Dependencies (same external/internal deps)
• ✅ Test interface (same test requirements)
• ✅ Module structure (same file organization)

## Output Location

Specifications are saved to: `Specs/[module-name].md`

This keeps all module specifications in a central, discoverable location.

## Integration with Builder Agent

After spec generation, the Builder Agent can:
1. Read the specification
2. Implement the module exactly as specified
3. Verify implementation matches spec
4. Run tests defined in spec
5. Regenerate modules when requirements change

## Quality Checks

After generating a spec, verify:

1. **Can someone rebuild the module from this spec?**
   - Yes = spec is complete
   - No = add missing details

2. **Does every exported function have a clear purpose?**
   - Yes = public interface is clear
   - No = combine or clarify functions

3. **Are all dependencies justified?**
   - Yes = move forward
   - No = remove or replace with simpler approach

4. **Would this prevent breaking other modules?**
   - Yes = studs are well-defined
   - No = clarify connection points

## Common Pitfalls to Avoid

- **Over-specification**: Don't specify implementation details
- **Under-documentation**: Document WHY, not just WHAT
- **Ambiguous contracts**: Be precise about inputs/outputs
- **Unclear dependencies**: Explicitly list all external/internal deps
- **Missing examples**: Always include working code examples
- **Ignored test requirements**: Tests define contract completeness

## Success Criteria

A good module spec:
- [ ] Single, clear responsibility
- [ ] Complete public interface documentation
- [ ] Explicit dependency list
- [ ] Realistic test requirements
- [ ] Working code examples
- [ ] Someone can rebuild module from it
- [ ] Regeneration preserves all connections
- [ ] Follows brick philosophy
- [ ] No future-proofing or speculation
- [ ] Regeneratable without breaking system

Module Spec Generation: Analysis Workflow

This document walks through the step-by-step process of analyzing an existing module and generating its specification.

Example: Analyzing the String Utils Module

Suppose we have an existing module at ~/.amplihack/.claude/tools/amplihack/string_utils/ and we want to generate its specification.

Step 1: Explore Module Structure

ls -la .claude/tools/amplihack/string_utils/

Output:
├── __init__.py
├── core.py
├── utils.py
├── tests/
│   ├── test_core.py
│   ├── test_utils.py
│   └── fixtures/
│       └── sample_text.txt
└── examples/
    └── usage.py

What we learned:

• Main code in core.py and utils.py
• Tests in tests/ directory
• Examples provided
• Appears to be well-organized

Step 2: Read the Public Interface (init.py)

# .claude/tools/amplihack/string_utils/__init__.py
from .core import truncate, normalize, slugify
from .utils import TextMetrics, COMMON_STOPWORDS

__all__ = ["truncate", "normalize", "slugify", "TextMetrics", "COMMON_STOPWORDS"]

What we learned:

• Exports: three functions and one class
• Primary exports from core.py
• Utility exports from utils.py

Step 3: Analyze Core Functions

# .claude/tools/amplihack/string_utils/core.py

def truncate(text: str, max_length: int, suffix: str = "...") -> str:
    """Truncate text to maximum length, appending suffix if truncated.

    Args:
        text: String to truncate
        max_length: Maximum length including suffix
        suffix: String to append if truncated (default: "...")

    Returns:
        Truncated string, max length as specified

    Raises:
        ValueError: If max_length < len(suffix)
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    if max_length < len(suffix):
        raise ValueError(...)

    if len(text) <= max_length:
        return text

    return text[:max_length - len(suffix)] + suffix


def normalize(text: str) -> str:
    """Normalize whitespace by removing leading/trailing and collapsing internal.

    Args:
        text: String to normalize

    Returns:
        String with normalized whitespace
    """
    return ' '.join(text.split())


def slugify(text: str, max_length: int = None) -> str:
    """Convert text to URL-safe slug (lowercase, hyphens, alphanumeric only).

    Args:
        text: String to convert
        max_length: Optional maximum length for slug

    Returns:
        URL-safe slug in lowercase

    Raises:
        ValueError: If result would be empty
    """
    slug = '-'.join(
        word for word in text.lower().split()
        if word.isalnum() or '-' in word
    )

    if not slug:
        raise ValueError("Slugify resulted in empty string")

    if max_length:
        slug = truncate(slug, max_length, '')

    return slug

What we learned:

• Three focused functions
• Good docstrings with Args, Returns, Raises
• Type hints present
• Error handling clear
• Truncate is used by slugify (internal dependency)

Step 4: Analyze Utilities

# .claude/tools/amplihack/string_utils/utils.py

class TextMetrics:
    """Analyze and report string metrics."""

    def __init__(self, text: str):
        self.text = text

    def word_count(self) -> int:
        """Return number of words."""
        return len(self.text.split())

    def char_count(self) -> int:
        """Return character count."""
        return len(self.text)

    def avg_word_length(self) -> float:
        """Return average word length."""
        words = self.text.split()
        return sum(len(w) for w in words) / len(words) if words else 0


COMMON_STOPWORDS = {
    "a", "an", "and", "are", "as", "at", "be", "but", "by",
    "for", "from", "has", "he", "in", "is", "it", "its", "of",
    "on", "or", "that", "the", "to", "was", "with"
}

What we learned:

• TextMetrics class for analysis
• Three simple methods
• COMMON_STOPWORDS constant (pre-defined set)

Step 5: Check Test Coverage

# .claude/tools/amplihack/string_utils/tests/test_core.py

class TestTruncate:
    def test_truncate_longer_string(self):
        assert truncate("Hello World", 8, "...") == "Hello..."

    def test_no_truncate_if_short(self):
        assert truncate("Hi", 8) == "Hi"

    def test_invalid_max_length(self):
        with pytest.raises(ValueError):
            truncate("text", 2, "...")

    # ... more tests


class TestNormalize:
    def test_normalize_spaces(self):
        assert normalize("  Hello   World  ") == "Hello World"

    def test_normalize_newlines(self):
        assert normalize("Hello\n\nWorld") == "Hello World"

    # ... more tests


class TestSlugify:
    def test_basic_slugify(self):
        assert slugify("Hello World") == "hello-world"

    def test_slugify_with_special_chars(self):
        assert slugify("Hello & World!") == "hello-world"

    def test_empty_result_raises(self):
        with pytest.raises(ValueError):
            slugify("!!!")

What we learned:

• Good test coverage
• Tests normal cases, edge cases, and errors
• Uses pytest

Step 6: Review Examples

# .claude/tools/amplihack/string_utils/examples/usage.py

from string_utils import truncate, normalize, slugify, TextMetrics

# Example 1: Truncation
title = "The Quick Brown Fox Jumps Over The Lazy Dog"
print(truncate(title, 20))  # "The Quick Brown F..."

# Example 2: Normalization
messy = "  Hello    World  \n  How are you?  "
print(normalize(messy))  # "Hello World How are you?"

# Example 3: Slugification
article = "Python & Django Best Practices!"
print(slugify(article))  # "python-django-best-practices"

# Example 4: Text metrics
text = "Hello World"
metrics = TextMetrics(text)
print(f"Words: {metrics.word_count()}")      # 2
print(f"Chars: {metrics.char_count()}")      # 11
print(f"Avg len: {metrics.avg_word_length()}")  # 5.5

What we learned:

• Clear usage examples
• All functions demonstrated
• TextMetrics usage shown

Step 7: Check Dependencies

# Review all imports
# core.py: no imports (uses only builtins)
# utils.py: no imports (uses only builtins)
# tests: pytest (testing only, not runtime)

What we learned:

• Pure Python, no external dependencies
• Standard library only
• Even tests don't need external libraries (except pytest)

Step 8: Draft Specification

Based on the analysis above, we can now draft the specification:

# String Utils Specification

## Purpose

Provide common string manipulation utilities with consistent behavior and clear error handling.

## Public Interface

### Functions

- `truncate(text: str, max_length: int, suffix: str = "...") -> str`
- `normalize(text: str) -> str`
- `slugify(text: str, max_length: int = None) -> str`

### Classes

- `TextMetrics`: Analyze text with word_count(), char_count(), avg_word_length()

### Constants

- `COMMON_STOPWORDS`: Set of 18 common English words

## Dependencies

- External: None
- Internal: None

## Test Requirements

✅ Truncate: 5+ tests (normal, edge, error cases)
✅ Normalize: 4+ tests (spaces, newlines, empty, whitespace-only)
✅ Slugify: 4+ tests (basic, special chars, empty result, max_length)
✅ TextMetrics: 3+ tests (word_count, char_count, avg_word_length)
✅ Coverage: 85%+

## Module Structure

(as observed above)

## Example Usage

(from usage.py above)

Step 9: Validate Specification

Check that the spec:

• [ ] Accurately reflects the code
• [ ] Documents all exported items
• [ ] Lists all dependencies correctly
• [ ] Test requirements match actual tests
• [ ] Examples are working code
• [ ] Someone could rebuild module from this spec

Result: Specification is accurate and complete.

Step 10: Write Specification Document

Create /Specs/string-utils.md with complete specification incorporating all above analysis.

Practical Analysis Checklist

When analyzing a module to generate its spec:

Code Files

• [ ] Read all *.py files in module
• [ ] Identify __init__.py exports
• [ ] Extract all function signatures
• [ ] Document all classes and methods
• [ ] List all module constants
• [ ] Check for data models (dataclass, NamedTuple, etc.)

Dependencies

• [ ] List all imports in each file
• [ ] Categorize: standard library, external, internal
• [ ] Note version requirements if specified
• [ ] Identify circular dependencies (red flag)
• [ ] Check for optional dependencies

Tests

• [ ] Count test files and test functions
• [ ] Identify test coverage areas
• [ ] Note edge cases being tested
• [ ] Check error handling tests
• [ ] Look for integration tests

Documentation

• [ ] Read existing docstrings
• [ ] Review any READMEs
• [ ] Check for inline comments
• [ ] Look at examples

Module Structure

• [ ] Map directory organization
• [ ] Note what files handle what
• [ ] Identify test organization
• [ ] Check for example files

Philosophy Alignment

• [ ] Single responsibility: Does module do ONE thing?
• [ ] Simplicity: Are implementations straightforward?
• [ ] Dependencies: Are they justified?
• [ ] Public interface: Is it minimal and clear?
• [ ] Regeneratable: Could this module be rebuilt from the spec?

Common Patterns to Document

Pattern 1: Simple Function Module

✅ Functions only, no classes
✅ Single responsibility
✅ Pure Python, no dependencies
Example: string_utils

Pattern 2: Class-Based Module

✅ One main class (or small set)
✅ Related helper functions
✅ Data models if needed
Example: session_management

Pattern 3: Integration Module

✅ Wraps external service (API, database)
✅ Clear error handling
✅ Dependencies documented
Example: github_client

Pattern 4: Data Structures Module

✅ Primarily classes/dataclasses
✅ Minimal methods
✅ Focuses on schema/structure
Example: models

Specification Quality Metrics

After generating a spec, measure:

1. Completeness: Does it describe all public items? (100% = 1.0) 2. Clarity: Would someone understand how to use this? (1-5 scale) 3. Precision: Are types, errors, and returns specific? (1-5 scale) 4. Regenerability: Could someone rebuild from this spec? (1-5 scale)

Target: Completeness = 1.0, Clarity >= 4, Precision >= 4, Regenerability >= 4

Automation Possibilities

While this skill is designed for Claude to guide the analysis, future enhancements could include:

1. AST Analysis: Automatically extract function signatures 2. Import Analysis: Automatically categorize dependencies 3. Coverage Detection: Read coverage reports 4. Documentation Generation: Auto-populate from docstrings 5. Diff Detection: Compare spec vs. implementation

However, the human expertise in understanding PURPOSE and RESPONSIBILITY is irreplaceable and should always drive specification quality.

Session Management Module Specification

Issue: Example for module-spec-generator skill Type: Infrastructure Module Complexity: Intermediate

Purpose

Provide session lifecycle management with persistent storage, structured logging, and defensive file operations. Enables Claude sessions to persist state across invocations and maintain audit trails.

Scope

Handles:

• Session creation and lifecycle tracking
• Session persistence to JSON files
• Session retrieval and resumption
• Structured session logging
• Timeout and cleanup logic
• Defensive file operations with retries

Does NOT handle:

• Network/remote session storage
• Encryption or credential management
• User authentication (assumes authenticated sessions)
• Advanced session scheduling

Philosophy Alignment

• ✅ Ruthless Simplicity: Local file storage, JSON format, standard logging
• ✅ Single Responsibility: Session lifecycle management only
• ✅ Minimal Dependencies: Only standard library + defensive I/O
• ✅ Regeneratable: Spec completely defines storage contract

Public Interface (The "Studs")

Classes

class ClaudeSession:
    """Wrapper around Claude API session with timeout and state tracking.

    Attributes:
        session_id (str): Unique session identifier
        created_at (datetime): Session creation timestamp
        last_activity (datetime): Last activity timestamp
        status (str): Current status (active, paused, ended)
        metadata (dict): Custom session metadata
    """

    def __init__(self, session_id: str, timeout_seconds: int = 3600):
        """Initialize session wrapper.

        Args:
            session_id: Unique identifier for this session
            timeout_seconds: Inactivity timeout in seconds

        Raises:
            ValueError: If session_id is empty or invalid
        """

    def record_activity(self, action: str, details: dict = None) -> None:
        """Record activity in this session.

        Args:
            action: Activity type (e.g., "api_call", "user_input")
            details: Optional details about the activity

        Raises:
            RuntimeError: If session is not active
        """

    def is_active(self) -> bool:
        """Check if session is still active (not timed out).

        Returns:
            True if session is active, False if timed out or ended
        """

    def get_metadata(self, key: str, default=None):
        """Get metadata value for this session.

        Args:
            key: Metadata key to retrieve
            default: Default value if key not found

        Returns:
            Metadata value or default
        """

    def set_metadata(self, key: str, value) -> None:
        """Set metadata value for this session.

        Args:
            key: Metadata key
            value: Value to store
        """

class SessionManager:
    """Manages session persistence and retrieval.

    Attributes:
        session_dir (Path): Directory where sessions are stored
        registry_file (Path): JSON file tracking all sessions
    """

    def __init__(self, session_dir: str = ".claude/runtime/sessions"):
        """Initialize session manager.

        Args:
            session_dir: Directory for session storage

        Raises:
            ValueError: If session_dir path is invalid
        """

    def create_session(self, timeout_seconds: int = 3600) -> ClaudeSession:
        """Create and persist new session.

        Returns:
            New ClaudeSession instance

        Raises:
            IOError: If cannot write to session directory
        """

    def get_session(self, session_id: str) -> ClaudeSession:
        """Retrieve existing session from storage.

        Args:
            session_id: Session ID to retrieve

        Returns:
            ClaudeSession instance

        Raises:
            KeyError: If session not found
            IOError: If cannot read session file
        """

    def list_sessions(self, status: str = None) -> list:
        """List all sessions, optionally filtered by status.

        Args:
            status: Filter by status (active, paused, ended)

        Returns:
            List of session IDs

        Raises:
            IOError: If cannot read session registry
        """

    def save_session(self, session: ClaudeSession) -> None:
        """Persist session state to storage.

        Args:
            session: Session to save

        Raises:
            IOError: If cannot write session
        """

    def archive_session(self, session_id: str) -> None:
        """Move completed session to archive.

        Args:
            session_id: Session to archive

        Raises:
            KeyError: If session not found
            IOError: If cannot move file
        """

class ToolkitLogger:
    """Structured logging for sessions and toolkit operations.

    Attributes:
        logger (logging.Logger): Underlying Python logger
    """

    def __init__(self, name: str, log_file: str = None):
        """Initialize logger.

        Args:
            name: Logger name (typically module name)
            log_file: Optional file to write logs to
        """

    def log_session_event(self, session_id: str, event: str, details: dict = None) -> None:
        """Log session-specific event.

        Args:
            session_id: Session this event belongs to
            event: Event type
            details: Optional event details
        """

    def log_error(self, message: str, exception: Exception = None) -> None:
        """Log error with optional exception details.

        Args:
            message: Error message
            exception: Optional exception object
        """

    def log_decision(self, what: str, why: str, alternatives: str = None) -> None:
        """Log a decision point for audit trail.

        Args:
            what: What was decided
            why: Why this decision was made
            alternatives: Alternative options considered
        """

Functions

def create_session_dir(path: str) -> Path:
    """Create session directory with proper structure.

    Args:
        path: Directory path to create

    Returns:
        Path object for created directory

    Raises:
        IOError: If cannot create directory
    """

def load_session_registry(registry_file: str) -> dict:
    """Load session registry from JSON file.

    Args:
        registry_file: Path to registry JSON file

    Returns:
        Dictionary of session metadata

    Raises:
        IOError: If file not readable
        ValueError: If JSON is malformed
    """

def save_with_retry(
    file_path: str,
    content: str,
    max_retries: int = 3,
    retry_delay: float = 0.1
) -> None:
    """Write file with automatic retry on failure.

    Args:
        file_path: Path to file to write
        content: Content to write
        max_retries: Maximum number of retry attempts
        retry_delay: Delay between retries in seconds

    Raises:
        IOError: If all retries exhausted
    """

Dependencies

External

None - pure Python standard library only.

Internal

None - completely standalone.

Standard Library Used

• json: Session serialization
• pathlib: File path handling
• datetime: Timestamps and timeout tracking
• logging: Structured logging
• uuid: Session ID generation
• time: Timeout calculations
• threading: Optional for timeout enforcement

Module Structure

session_management/
├── __init__.py                  # Public exports
├── claude_session.py            # ClaudeSession class
├── session_manager.py           # SessionManager class
├── toolkit_logger.py            # ToolkitLogger class
├── file_utils.py                # Defensive file operations
├── tests/
│   ├── __init__.py
│   ├── test_session.py         # ClaudeSession tests
│   ├── test_manager.py         # SessionManager tests
│   ├── test_logger.py          # ToolkitLogger tests
│   ├── test_file_utils.py      # File operation tests
│   └── fixtures/
│       ├── sample_session.json
│       └── sample_registry.json
└── examples/
    ├── basic_usage.py
    └── persistent_session.py

Module Boundaries

init.py

from .claude_session import ClaudeSession
from .session_manager import SessionManager
from .toolkit_logger import ToolkitLogger
from .file_utils import save_with_retry, load_with_retry

__all__ = [
    "ClaudeSession",
    "SessionManager",
    "ToolkitLogger",
    "save_with_retry",
    "load_with_retry",
]

claude_session.py

ClaudeSession class implementation. Responsible for single session lifecycle.

session_manager.py

SessionManager class implementation. Handles storage and retrieval operations.

toolkit_logger.py

ToolkitLogger class implementation. Structured logging wrapper.

file_utils.py

Defensive file operations: save_with_retry, load_with_retry, etc.

Test Requirements

ClaudeSession Tests

• ✅ Create session with unique ID
• ✅ Track creation and activity timestamps
• ✅ Timeout detection works correctly
• ✅ is_active() returns correct status
• ✅ Metadata get/set operations
• ✅ Cannot record activity on inactive session
• ✅ Invalid session_id raises ValueError

SessionManager Tests

• ✅ Create new session
• ✅ Save session to JSON
• ✅ Load session from JSON
• ✅ List all sessions
• ✅ List sessions filtered by status
• ✅ Archive completed sessions
• ✅ Registry stays in sync with files
• ✅ Handle missing directory gracefully
• ✅ Handle corrupted session files
• ✅ Cannot load non-existent session (KeyError)

ToolkitLogger Tests

• ✅ Create logger with name
• ✅ Log session events
• ✅ Log errors with exceptions
• ✅ Log decisions for audit trail
• ✅ Log file is created and written
• ✅ Log rotation works if configured
• ✅ No errors if log file unavailable

File Operations Tests

• ✅ save_with_retry succeeds on first try
• ✅ save_with_retry retries on failure
• ✅ save_with_retry gives up after max retries
• ✅ load_with_retry handles missing files
• ✅ JSON encoding/decoding works
• ✅ Concurrent writes don't corrupt data

Integration Tests

• ✅ Create session → save → load → verify integrity
• ✅ Session timeout detection across load/save cycle
• ✅ Metadata persists through save/load
• ✅ Multiple sessions don't interfere
• ✅ Archive moves files correctly

Coverage

85%+ line coverage across all classes and functions.

Example Usage

from session_management import (
    ClaudeSession,
    SessionManager,
    ToolkitLogger,
)

# Create manager
manager = SessionManager(".claude/runtime/sessions")

# Create new session
session = manager.create_session(timeout_seconds=3600)
print(f"Created session: {session.session_id}")

# Record activity
session.record_activity("user_input", {"message": "Hello"})

# Set and get metadata
session.set_metadata("user", "alice@example.com")
user = session.get_metadata("user")

# Save session
manager.save_session(session)

# Later: retrieve session
retrieved = manager.get_session(session.session_id)
print(f"Session active: {retrieved.is_active()}")

# List all active sessions
active_sessions = manager.list_sessions(status="active")
print(f"Active sessions: {len(active_sessions)}")

# Logging
logger = ToolkitLogger(__name__, ".claude/runtime/logs/toolkit.log")
logger.log_session_event(session.session_id, "completed")
logger.log_decision(
    what="Archive session",
    why="Session timeout reached",
    alternatives="Extend timeout, delete session"
)

Runtime Structure

Sessions persist in this structure:

.claude/runtime/
├── sessions/
│   ├── registry.json           # All session metadata
│   ├── session_abc123.json     # Individual session files
│   ├── session_def456.json
│   └── archive/
│       └── session_old789.json # Archived sessions
└── logs/
    ├── toolkit.log             # Structured logs
    └── session_abc123.log      # Per-session logs

Storage Format

registry.json

{
  "sessions": {
    "abc123": {
      "created_at": "2025-11-08T10:30:00Z",
      "status": "active",
      "timeout_seconds": 3600
    },
    "def456": {
      "created_at": "2025-11-08T09:00:00Z",
      "status": "archived",
      "timeout_seconds": 3600
    }
  }
}

session\_\*.json

{
  "session_id": "abc123",
  "created_at": "2025-11-08T10:30:00Z",
  "last_activity": "2025-11-08T10:35:15Z",
  "status": "active",
  "timeout_seconds": 3600,
  "metadata": {
    "user": "alice@example.com",
    "branch": "main"
  },
  "activity_log": [
    {
      "action": "user_input",
      "timestamp": "2025-11-08T10:30:05Z",
      "details": { "message": "Hello" }
    }
  ]
}

Regeneration Notes

This module can be rebuilt from this specification while maintaining:

• ✅ Public interface (ClaudeSession, SessionManager, ToolkitLogger)
• ✅ Session storage contract (JSON format, registry structure)
• ✅ Logging interface (log methods and formats)
• ✅ File operations (defensive I/O with retries)
• ✅ Error handling (same exceptions, same conditions)

Any new implementation can be verified by:

1. Checking all classes and functions exist with correct signatures 2. Running the test suite (all 40+ tests pass) 3. Running persistence examples 4. Verifying coverage >= 85% 5. Checking session files maintain correct structure

Quality Checklist

• [ ] Single responsibility: Session management only
• [ ] Public interface complete: All classes and functions listed
• [ ] Dependencies explicit: Standard library only
• [ ] Storage format defined: JSON structure specified
• [ ] Tests exhaustive: All scenarios covered
• [ ] Examples working: All code in this spec is valid Python
• [ ] Spec is complete: Could rebuild module from this spec alone
• [ ] Error handling clear: All exceptions documented
• [ ] Follows simplicity: Three classes, defensive I/O, no complexity

String Utils Specification

Issue: Example for module-spec-generator skill Type: Utility Module Complexity: Simple

Purpose

Provide common string manipulation utilities with consistent behavior and clear error handling. Single responsibility: transform strings according to well-defined rules.

Scope

Handles:

• Text truncation with length constraints
• Whitespace normalization
• URL-safe slug conversion
• Clear, simple operations

Does NOT handle:

• Internationalization (i18n) or complex Unicode handling
• Regular expression validation
• HTML/XML parsing or encoding
• Text encoding (assumes UTF-8)

Philosophy Alignment

• ✅ Ruthless Simplicity: Three focused functions, no abstractions
• ✅ Single Responsibility: String manipulation utilities only
• ✅ No External Dependencies: Pure Python standard library only
• ✅ Regeneratable: Spec completely defines implementation contract

Public Interface (The "Studs")

Functions

def truncate(text: str, max_length: int, suffix: str = "...") -> str:
    """Truncate text to maximum length, appending suffix if truncated.

    Args:
        text: String to truncate
        max_length: Maximum length including suffix
        suffix: String to append if truncated (default: "...")

    Returns:
        Truncated string, max length as specified

    Raises:
        ValueError: If max_length < len(suffix)
        TypeError: If text is not a string

    Example:
        >>> truncate("Hello World", 8, "...")
        'Hello...'
        >>> truncate("Hi", 8)
        'Hi'
    """

def normalize(text: str) -> str:
    """Normalize whitespace by removing leading/trailing and collapsing internal.

    Args:
        text: String to normalize

    Returns:
        String with normalized whitespace

    Raises:
        TypeError: If text is not a string

    Example:
        >>> normalize("  Hello   World  ")
        'Hello World'
        >>> normalize("Line\n  \n  2")
        'Line 2'
    """

def slugify(text: str, max_length: int = None) -> str:
    """Convert text to URL-safe slug (lowercase, hyphens, alphanumeric only).

    Args:
        text: String to convert
        max_length: Optional maximum length for slug

    Returns:
        URL-safe slug in lowercase

    Raises:
        TypeError: If text is not a string
        ValueError: If result would be empty

    Example:
        >>> slugify("Hello World!")
        'hello-world'
        >>> slugify("Python & Django", 10)
        'python'
    """

Constants

None - this module has no module-level constants.

No Classes

This module exports only functions. It does not define custom classes or data models.

Dependencies

External

None - pure Python standard library only.

Internal

None - completely standalone module.

Standard Library Used

• string module for character classifications
• re module for pattern matching (optional, only if needed)

Module Structure

string_utils/
├── __init__.py              # Exports: truncate, normalize, slugify
├── core.py                  # All three functions implemented here
├── tests/
│   ├── __init__.py
│   ├── test_truncate.py    # Tests for truncate function
│   ├── test_normalize.py   # Tests for normalize function
│   ├── test_slugify.py     # Tests for slugify function
│   └── fixtures/
│       └── sample_text.txt # Sample text for testing
└── examples/
    └── usage.py            # Usage examples

Module Boundaries

init.py

from .core import truncate, normalize, slugify

__all__ = ["truncate", "normalize", "slugify"]

core.py

Contains all three function implementations. Focus on clarity and correctness, not optimization.

tests/

Four separate test files, one per function, plus shared fixtures.

Test Requirements

truncate() Tests

• ✅ Truncate longer string with default suffix
• ✅ Truncate with custom suffix
• ✅ Don't truncate if already short enough
• ✅ Raise ValueError if max_length < suffix length
• ✅ Handle edge case: text exactly max_length
• ✅ Handle edge case: text one char longer than max_length
• ✅ Raise TypeError if text is not string

normalize() Tests

• ✅ Remove leading whitespace
• ✅ Remove trailing whitespace
• ✅ Collapse multiple spaces to single space
• ✅ Handle tabs and newlines as whitespace
• ✅ Already normalized text unchanged
• ✅ Empty string returns empty string
• ✅ Whitespace-only string returns empty string
• ✅ Raise TypeError if text is not string

slugify() Tests

• ✅ Convert to lowercase
• ✅ Replace spaces with hyphens
• ✅ Remove special characters
• ✅ Remove punctuation
• ✅ Handle consecutive hyphens
• ✅ Return empty slug → raise ValueError
• ✅ Optional max_length truncation
• ✅ Raise TypeError if text is not string

Coverage

85%+ line coverage across all functions.

Example Usage

from string_utils import truncate, normalize, slugify

# Truncation examples
title = "The Quick Brown Fox Jumps Over The Lazy Dog"
short = truncate(title, 20)
print(short)  # "The Quick Brown F..."

# Normalization examples
messy = "  Hello    World  \n  How are you?  "
clean = normalize(messy)
print(clean)  # "Hello World How are you?"

# Slugify examples
article_title = "Python & Django Best Practices!"
slug = slugify(article_title)
print(slug)  # "python-django-best-practices"

# With length constraint
slug_short = slugify(article_title, max_length=15)
print(slug_short)  # "python-django"

Implementation Notes

Simplicity First

These implementations should be straightforward:

# Example: truncate - simple, no tricks
def truncate(text: str, max_length: int, suffix: str = "...") -> str:
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    if max_length < len(suffix):
        raise ValueError("max_length must be >= suffix length")

    if len(text) <= max_length:
        return text

    return text[:max_length - len(suffix)] + suffix

No Over-Engineering

• Don't add configuration options not in the spec
• Don't optimize prematurely
• Don't anticipate future uses
• Keep implementations obvious and readable

Error Clarity

When raising errors:

• Include the problematic value
• Explain what was wrong
• Suggest how to fix it

raise ValueError(
    f"max_length ({max_length}) must be >= suffix length ({len(suffix)})"
)

Regeneration Notes

This module can be rebuilt from this specification while maintaining:

• ✅ Public contract (truncate, normalize, slugify always available)
• ✅ Function signatures (same types, same behavior)
• ✅ Error handling (same exceptions, same conditions)
• ✅ Test interface (all test requirements preserved)
• ✅ Module structure (same files and organization)

Any new implementation can be verified by:

1. Checking all three functions exist with correct signatures 2. Running the test suite 3. Checking that all examples work correctly 4. Verifying coverage >= 85%

Quality Checklist

• [ ] Single responsibility: String utilities only
• [ ] Public interface complete: truncate, normalize, slugify
• [ ] Dependencies explicit: Standard library only
• [ ] Tests exhaustive: Cover normal, edge, and error cases
• [ ] Examples working: All code in this spec is valid Python
• [ ] Spec is complete: Could rebuild module from this spec alone
• [ ] No implementation details: Just the contract
• [ ] Clear error messages: When things fail
• [ ] Follows simplicity: Three functions, no complexity

Module Spec Generator: Quick Reference

When to Use This Skill

Specification Template (One Page)

````markdown

[Module Name] Specification

Purpose

[One sentence describing core responsibility]

Public Interface

Functions

def function_name(param: Type) -> ReturnType:
    """Brief description.
    Args: ...
    Returns: ...
    Raises: ...
    """

````

Classes

• ClassName: Description with key methods

Constants

• CONSTANT_NAME: Description

Dependencies

• External: [package name (version)]
• Internal: [module path]

Module Structure

module_name/
├── __init__.py
├── core.py
├── tests/
└── examples/

Test Requirements

• ✅ Test 1: description
• ✅ Test 2: description
• ✅ Coverage: 85%+

Example Usage

from module_name import function, Class
# usage examples

Regeneration Notes

This module can be rebuilt from this spec preserving:

• ✅ Public contract
• ✅ Dependencies
• ✅ Test interface

## Brick Philosophy Checklist

BRICK = Self-contained module with ONE clear responsibility STUD = Public connection point (function/class/API) REGENERATABLE = Can rebuild without breaking connections

**Every spec must answer:**
- [ ] What is the SINGLE core responsibility?
- [ ] What are the PUBLIC "studs"?
- [ ] What dependencies does it have?
- [ ] Can someone rebuild it from this spec alone?

## Common Mistakes to Avoid

| Mistake | Wrong | Right |
|---------|-------|-------|
| Multiple responsibilities | "Handles auth, validation, caching" | "Validates JWTs" |
| Implementation details | "Use Pydantic + Redis" | "Validate and cache" |
| Vague signatures | "def check(x)" | "def validate(token: str) -> Payload" |
| Missing errors | "Returns result" | "Raises ValueError if invalid" |
| No examples | "See code for usage" | Include 3-5 working examples |
| Unclear dependencies | "Some packages" | "PyJWT 2.8+, PyYAML 6.0+" |

## Analysis Workflow (Steps 1-10)

1. **Explore Structure**: `ls -la module_dir/` - map files
2. **Read Exports**: `cat __init__.py` - see `__all__`
3. **Analyze Functions**: Read function signatures and docstrings
4. **Document Classes**: Classes, attributes, key methods
5. **Map Dependencies**: All imports, categorize them
6. **Check Tests**: Count tests, identify coverage areas
7. **Review Examples**: Look for working code
8. **Draft Spec**: Synthesize all findings
9. **Validate Spec**: Verify completeness
10. **Write Document**: Create Specs/module-name.md

## File Locations

.claude/skills/module-spec-generator/ ├── SKILL.md # Full skill documentation ├── README.md # Skill overview and philosophy ├── QUICK_REFERENCE.md # This file ├── examples/ │ ├── simple-utility-spec.md # Simple module example │ ├── session-management-spec.md # Complex module example │ └── analysis-workflow.md # Step-by-step analysis

## Key Principles

### Ruthless Simplicity
- No unnecessary abstractions
- Functions do one thing
- No future-proofing
- Obvious implementations

### Single Responsibility
- Module has ONE core job
- "Handles X" not "Handles A, B, C, D"
- Everything serves that core purpose

### No External Dependencies (When Possible)
- Pure Python > external package
- Standard library > PyPI
- Dependencies justified explicitly

### Regeneratable
- Spec is THE source of truth
- Can rebuild module from spec alone
- Implementation is just details
- Preserves all connection points

### Clear Contracts
- All exports documented
- Type hints specified
- Errors explicit
- Examples provided

## Spec Length Guidelines

| Module Type | Typical Spec Length |
|-------------|-------------------|
| Utility functions (3-5 functions) | 1-2 pages |
| Class-based module (1-2 classes) | 2-3 pages |
| Integration module (API wrapper) | 3-4 pages |
| Complex infrastructure | 4-5 pages |

*If spec exceeds 5 pages, module probably does too much - consider splitting it.*

## Questions to Ask While Analyzing

1. **Purpose**: What is the ONE core job of this module?
2. **Interface**: What exactly is exported? Are names clear?
3. **Usage**: How would someone use this?
4. **Dependencies**: Why is each dependency needed?
5. **Errors**: What can fail and how is it handled?
6. **Tests**: What behaviors must be guaranteed?
7. **Regeneration**: Could I rebuild this from the spec?

## Spec Validation Questions

- [ ] Is there ONE clear core responsibility?
- [ ] Are all exports documented?
- [ ] Are type hints specified?
- [ ] Are error conditions documented?
- [ ] Are examples provided and working?
- [ ] Are dependencies justified?
- [ ] Are test requirements clear?
- [ ] Could someone rebuild from this spec?
- [ ] Does it follow brick philosophy?
- [ ] Would implementation match spec exactly?

## Integration Points

### Creating New Modules
1. Generate spec with this skill
2. Review and refine with team
3. Pass to Builder Agent
4. Builder implements from spec
5. Reviewer verifies code matches spec

### Documenting Existing Modules
1. Analyze module with this skill
2. Generate spec
3. Compare spec vs code
4. Update spec if needed
5. Store in Specs/ for reference

### Architecture Decisions
1. Use this skill to clarify design
2. Generate spec for review
3. Debate alternatives based on specs
4. Choose best approach
5. Implement from final spec

## Common Module Types

### Type 1: Utility Functions
**Example**: string_utils, math_utils, path_utils

Public Interface: 3-5 focused functions Dependencies: Often none (pure Python) Tests: Unit tests for each function Complexity: Low Spec Size: 1-2 pages

### Type 2: Class-Based Module
**Example**: session_management, configuration, models

Public Interface: 1-3 classes + helper functions Dependencies: Usually internal + standard library Tests: Unit tests + integration tests Complexity: Medium Spec Size: 2-3 pages

### Type 3: Integration Module
**Example**: github_client, database_driver, api_wrapper

Public Interface: High-level functions wrapping external service Dependencies: External package + internal models Tests: Unit + integration + fixture handling Complexity: Medium-High Spec Size: 3-4 pages

### Type 4: Data Models
**Example**: config models, database schemas, message formats

Public Interface: Classes/dataclasses with fields Dependencies: Often none Tests: Validation + serialization tests Complexity: Low Spec Size: 1-2 pages

## Examples in This Skill

1. **simple-utility-spec.md**
   - Type: Utility functions (truncate, normalize, slugify)
   - Complexity: Low
   - Use as template for simple modules

2. **session-management-spec.md**
   - Type: Class-based infrastructure
   - Complexity: Medium
   - Use as template for complex modules

3. **analysis-workflow.md**
   - Real-world step-by-step analysis
   - Shows how to extract spec from existing code
   - Use as process guide

## Success Indicators

✅ **Your spec is good if...**
- Someone could rebuild the module without asking questions
- All functions/classes are explained
- Error conditions are clear
- Examples actually work
- Dependencies are justified
- It's 1-4 pages (concise)
- Follows brick philosophy
- Matches the actual implementation

❌ **Your spec needs work if...**
- You're unsure what the module does
- You can't explain it in one sentence
- There are multiple core responsibilities
- Dependencies aren't justified
- Examples don't work
- Test requirements are vague
- It's more than 5 pages
- It describes HOW instead of WHAT

## Next Steps After Spec

1. **For new modules**: Pass spec to Builder Agent
2. **For existing modules**: File in Specs/ directory
3. **For architecture**: Use spec to debate design
4. **For reviews**: Reference spec as contract
5. **For updates**: Update spec first, then code

## Module Regeneration Process

When code needs updating:

1. Update spec with new requirements ↓ 2. Pass updated spec to Builder Agent ↓ 3. Builder rebuilds module to match new spec ↓ 4. Tests verify behavior matches spec ↓ 5. Module is updated ↓ 6. All connections preserved (studs unchanged)

This is why clear specs enable rapid iteration.

Claude Code Skills for Amplihack

This directory contains production-ready Claude Code Skills that extend amplihack's capabilities across coding, creative work, knowledge management, and document processing.

📚 About Claude Code Skills

Claude Code Skills are modular, reusable capabilities that extend Claude's functionality. They consist of folders containing a SKILL.md file with YAML frontmatter and Markdown instructions, along with optional supporting scripts and resources.

Key Benefits:

• Token Efficient: Skills load on-demand, consuming minimal tokens until needed
• Philosophy Aligned: All skills follow amplihack's ruthless simplicity and modular design
• Portable: Work across Claude.ai, API, and Claude Code environments
• Self-Contained: Each skill is independently usable and testable

🎯 Implemented Skills

Core Skills (12 Total)

Phase 1: Quick Wins (4 skills)

Phase 2: Philosophy Enforcement (3 skills)

Phase 3: Creative (2 skills)

Phase 4: Advanced (3 skills)

Office Document Skills (4 Skills)

Anthropic's office document skills integrated into amplihack for comprehensive document processing capabilities.

📖 Research & Documentation

Research Reports

• [Complete Research Report](../runtime/logs/20251108_skills_research/RESEARCH.md) (357 lines)
• Comprehensive analysis of Claude Code Skills ecosystem
• Comparison with MCP (Model Context Protocol)
• 23+ documented skills from Anthropic and community
• Key insights from Simon Willison and other experts

• [Evaluation Matrix & Ideas](../runtime/logs/20251108_skills_research/EVALUATION_MATRIX_AND_IDEAS.md) (842 lines)
• 6-criteria evaluation framework aligned with amplihack philosophy
• 20 brainstormed skill ideas with priority scores
• Implementation phases and effort estimates
• Detailed scoring rubrics

Evaluation Criteria

All skills were evaluated on:

1. Ruthless Simplicity (1-5): Single clear purpose, minimal dependencies 2. Modular Design (1-5): Self-contained, clear interfaces (bricks & studs) 3. Zero-BS Implementation (1-5): Actually works, no stubs 4. Reusability (1-5): Useful across multiple contexts 5. Maintenance Burden (1-5, lower is better): Stable dependencies 6. User Value (1-5): Solves frequent pain points, measurable time savings

Priority Score Formula:

Priority = (Simplicity * 2) + (Modular * 2) + (Zero-BS * 1.5) +
           (Reusability * 1.5) + ((6 - Maintenance) * 1) + (User Value * 2.5)
Max Score: 50 points

🔍 Using Skills

Skills are automatically discovered from:

• User settings: ~/.config/claude/skills/
• Project settings: ~/.amplihack/.claude/skills/
• Plugin-provided skills
• Built-in skills

Invoking Skills

Claude, use the decision-logger skill to record this architectural decision.

Claude, analyze test coverage using test-gap-analyzer.

Claude, generate a Mermaid diagram for this workflow using mermaid-diagram-generator.

Claude, extract all tables from sales_report.pdf to Excel using the pdf skill.

Managing Skills

/agents                # List available agents and skills
/reload-skills         # Reload after modifications

🏗️ Skill Structure

Each skill follows this structure:

skill-name/
├── SKILL.md           # Required: YAML frontmatter + instructions
├── README.md          # Optional: User-facing documentation
├── DEPENDENCIES.md    # Optional: Dependency documentation (Office skills)
├── examples/          # Optional: Example usage
└── tests/             # Optional: Validation tests

SKILL.md Format

---
name: skill-name
description: |
  Clear description of what this skill does and when Claude should use it.
  Include both the capability AND the usage context.
---

# Skill Instructions

Detailed instructions for Claude on how to use this skill...

## Examples
Concrete examples with input/output...

📊 Quality Standards

All skills meet these quality standards:

• ✅ Complete Documentation: SKILL.md with YAML frontmatter
• ✅ Clear Examples: Real-world usage demonstrations
• ✅ Philosophy Aligned: Ruthless simplicity, modular design, zero-BS
• ✅ Tested: Quality review completed
• ✅ Production Ready: No stubs, TODOs, or placeholders

🚀 Office Skills Quick Start

1. Choose Your Skill

Identify which document type you need to work with:

• PDF files → Use pdf skill
• Excel files (.xlsx) → Use xlsx skill (coming soon)
• Word documents (.docx) → Use docx skill (coming soon)
• PowerPoint slides (.pptx) → Use pptx skill (coming soon)

2. Install Dependencies

Each skill has different dependencies. See skill-specific DEPENDENCIES.md:

# For PDF skill
pip install pypdf pdfplumber reportlab pandas

# Optional OCR support
pip install pytesseract pdf2image
brew install tesseract poppler  # macOS

3. Verify Installation

Use the verification script to check dependencies:

cd .claude/skills
python common/verification/verify_skill.py pdf

4. Use in Claude Code

Simply mention the task in conversation:

User: Extract all tables from sales_report.pdf to Excel
Claude: [Uses PDF skill to extract and convert tables]

User: Create a professional PDF report with our Q4 data
Claude: [Uses PDF skill to generate formatted report]

Office Skills Architecture

Directory Structure

.claude/skills/
├── README.md                    # This file
├── INTEGRATION_STATUS.md        # Office skills integration tracker
├── common/                      # Shared infrastructure for Office skills
│   ├── README.md
│   ├── dependencies.txt         # Shared dependencies
│   ├── ooxml/                   # OOXML scripts (docx + pptx)
│   └── verification/            # Dependency verification
├── pdf/                         # PDF skill
│   ├── SKILL.md                 # Official skill definition
│   ├── README.md                # Integration notes
│   ├── DEPENDENCIES.md          # Dependency documentation
│   ├── examples/
│   └── tests/
├── decision-logger/             # Core skill example
├── email-drafter/               # Core skill example
└── ... (other skills)

Design Principles

Each skill follows amplihack's brick philosophy:

1. Self-contained: All skill code in its directory 2. Clear contract: Well-defined inputs and outputs 3. Regeneratable: Can be rebuilt from specification 4. Independent: No cross-skill dependencies 5. Graceful degradation: Optional features skip cleanly

Philosophy Compliance

Skills integration follows amplihack's core principles:

Ruthless Simplicity

• Use established libraries, no custom parsers
• Minimal abstractions
• Direct, straightforward implementations

Modular Design

• Each skill is an independent brick
• Clear public contracts (SKILL.md)
• No implicit dependencies

Zero-BS Implementation

• No stubs or placeholders
• All code works or degrades gracefully
• No fake implementations

Explicit Over Implicit

• All dependencies documented
• No automatic installation
• Clear error messages with solutions

Regeneratable

• Each skill can be rebuilt from SKILL.md
• Documentation is specification
• Tests verify contracts

🤝 Contributing

When adding new skills:

1. Create GitHub issue with evaluation scores 2. Implement in separate worktree/branch 3. Follow naming: feat/issue-{number}-{skill-name} 4. Create PR with comprehensive description 5. Link to research and evaluation docs 6. Ensure quality review completed

📚 Related Documentation

• CLAUDE.md - Project overview and agent system
• PHILOSOPHY.md - Ruthless simplicity principles
• PATTERNS.md - Reusable solution patterns
• Agent Catalog - Specialized agents
• Office Skills Integration Status - Progress tracker

License

The Office skills are provided by Anthropic under their proprietary license. See individual SKILL.md files and Anthropic's LICENSE.txt for complete terms.

The amplihack integration code and core skills follow the amplihack project license.

---

Last Updated: November 9, 2025 Total Skills: 16 (12 core + 4 office) Status: Production Ready (12 core skills + 4 office skills integrated - COMPLETE!)

🤖 Skills documentation maintained as part of amplihack project