# Repository Purpose

> This file provides guidance to programming agents, like Claude Code (claude.ai/code), when working with code in this repository.

- Skill: `tools-only/repository-purpose-3` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/repository-purpose-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/repository-purpose-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/repository-purpose-3

---

# CLAUDE.md

This file provides guidance to programming agents, like Claude Code (claude.ai/code), when working with code in this repository.

## Repository Purpose

This repository packages The Swift Programming Language book from Apple into a Claude Skill format. The skill is automatically generated from the official Swift documentation repository. This repository is exposed as a Claude plugin marketplace which vends a plugin which contains the skill.

## Build Commands

### Generate the Skill Package
```bash
python3 package.py
```

This command:
- Clones the official Swift book repository (https://github.com/swiftlang/swift-book.git)
- Extracts and organizes the documentation content
- Generates the `programming-swift` directory with the skill content
- Creates `programming-swift.zip` archive for distribution
- Extracts the Swift version automatically from the documentation

### Build Options
- `--output DIR` or `-o DIR`: Specify custom output directory (default: `./programming-swift`)
- `--keep-temp`: Keep the temporary git clone after packaging
- `--dry-run`: Simulate operations without writing files

## Code Architecture

### Design Philosophy: Separation of Concerns

The repository manages two distinct responsibilities which are intentionally decoupled:

1.  **Skill Generation (`package.py`)**:
    *   **Goal**: To be a standalone, portable tool that transforms the Swift documentation into a canonical Claude Skill format.
    *   **Constraint**: It must have **zero dependencies** and be runnable by anyone, anywhere, to generate the skill.
    *   **Scope**: It strictly handles content extraction and generation. It generally *does not* know about the release process, versioning schemes, or marketplace metadata.

2.  **Distribution & Lifecycle (Repository & Workflow)**:
    *   **Goal**: To vend the generated skill via releases and the Claude Marketplace.
    *   **Scope**: This layer (handled by `.github/workflows/release.yml`) manages the "outer loop": running the generator, detecting changes, managing `marketplace.json`, and creating Git tags/releases.

**Implication**: Changes to `marketplace.json` or release logic should **never** be leaked into `package.py`.

### Main Components

1. **package.py**: The single-file packaging script with zero external dependencies
   - Manages temporary cloning of the Swift book repository
   - Extracts metadata and parses table of contents
   - Orchestrates skill directory creation and artifact generation
   - Handles runtime settings and constants

2. **GitHub Actions Workflow** (`.github/workflows/release.yml`):
   - Orchestrates the nightly release process
   - Handles content verification, committing, and releasing

3. **Claude Plugin Marketplace Integration** (`.claude-plugin/marketplace.json`):
   - Contains metadata for the Claude plugin marketplace
   - Automatically updated by the release workflow with Swift version

### Key Implementation Details

- The script parses `TSPL.docc/The-Swift-Programming-Language.md` to determine the correct document order
- Metadata is extracted from each markdown file (title from first `#` heading, description from first paragraph)
- The skill is organized into three sections: GuidedTour, LanguageGuide, and ReferenceManual
- Version is automatically extracted from the main TOC file and propagated throughout the skill
- Apache 2.0 license from the Swift repository is included for compliance

## Release Process

The repository uses a "release-on-change" strategy to minimize noise and version inflation:

1. **Nightly Trigger**: The GitHub Actions workflow runs every night.
2. **Generation**: It executes `package.py` to pull the latest documentation and generate the skill.
3. **Change Detection**: It compares the generated `programming-swift/` directory with the currently committed version.
4. **Conditional Release**:
   - **No Changes**: The workflow exits silently.
   - **Changes Detected**:
     - Updates `marketplace.json` with the new version (`SWIFT_VERSION-YYYY-MM-DD`).
     - Commits the new content and metadata to the repository.
     - Creates a GitHub Release with the new artifacts.

### Configuration

- **`RELEASE_TOKEN` Secret**: The release workflow on GitHub requires a repository secret named `RELEASE_TOKEN` (Personal Access Token with `repo` or `public_repo` scope) to create releases and tags attributed to the maintainer. If missing, it falls back to the default `github.token` (bot attribution).

## Skill Content Structure

The generated `programming-swift` directory contains:
- `SKILL.md`: The main index file with frontmatter metadata
- `GuidedTour/`: Getting started documentation
- `LanguageGuide/`: Comprehensive language features
- `ReferenceManual/`: Formal language reference
- `LICENSE.txt`: Apache 2.0 license from the Swift repository