zig-programming（之字形编程）

Zig Programming Language Skill

This skill provides expertise in Zig, a general-purpose programming language focused on robustness, optimality, and maintainability. The skill includes version-specific documentation (0.2.0 through master), automatic version detection, code templates, and comprehensive reference materials organized for progressive disclosure.

Table of Contents

• Bundled Resources

- References - Progressive disclosure documentation - Recipes - 223 tested recipes organized by topic - Templates - Starting points for common tasks - Examples - Practical code samples - Scripts - Automation tools

• Workflows
• Version Awareness
• Best Practices

Bundled Resources

References - Progressive Loading Guide

Important: References are version-specific. Use scripts/get_references.py to get the correct reference path for the detected Zig version, or load from references/latest/ (symlink to current stable: 0.15.2).

Load documentation progressively based on task complexity. Use this decision tree:

New to Zig? Start with fundamentals in order:

1. references/latest/core-language.md → Basic syntax, types, operators
2. references/latest/control-flow.md → If, while, for, switch
3. references/latest/functions-errors.md → Functions and error handling
4. references/latest/quick-reference.md → Syntax quick lookup

Solving specific problems? Jump directly to:

• Error handling → latest/functions-errors.md + latest/patterns-error-testing.md
• Memory/allocators → latest/memory-management.md + latest/patterns-memory-comptime.md
• Data structures → latest/arrays-slices.md, latest/structs-methods.md, latest/enums-unions.md, latest/pointers-references.md
• Struct/array/enum patterns → latest/patterns-data-structures.md
• Stdlib lookup → grep latest/stdlib-builtins.md (large file, 68KB)
• C interop → latest/c-interop.md + latest/patterns-integration.md
• Build system → latest/build-system.md + latest/patterns-integration.md

Advanced topics (after mastering fundamentals):

• references/latest/comptime.md - Compile-time execution and generics
• references/latest/patterns-memory-comptime.md - Advanced memory and comptime patterns
• references/latest/testing-quality.md - Testing framework and best practices

Version migration → references/version-differences.md (shared across versions, comprehensive migration guides)

Using version-specific references:

# Get reference path for detected version
python scripts/get_references.py
# Output: references/v0.15.2

# With specific version
python scripts/get_references.py --version 0.13.0
# Output: references/v0.15.2 (with fallback warning)

# JSON output for programmatic use
python scripts/get_references.py --json

Recipes - Cookbook

The skill includes 223 tested recipes from the Zig BBQ Cookbook, organized by topic. All recipes include complete, compilable code verified against Zig 0.15.2.

Finding recipes by topic:

• recipes/fundamentals.md - Philosophy, basics (19 recipes)
• recipes/data-structures.md - Arrays, hashmaps, sets (20 recipes)
• recipes/strings-text.md - String processing (14 recipes)
• recipes/memory-allocators.md - Allocator patterns (6 recipes)
• recipes/comptime-metaprogramming.md - Compile-time (24 recipes)
• recipes/structs-objects.md - Structs, unions (22 recipes)
• recipes/functions.md - Function patterns (11 recipes)
• recipes/files-io.md - File operations (19 recipes)
• recipes/networking.md - HTTP, sockets (18 recipes)
• recipes/concurrency.md - Threading, atomics (8 recipes)
• recipes/build-system.md - Build.zig, modules (18 recipes)
• recipes/testing-debugging.md - Testing (14 recipes)
• recipes/c-interop.md - C FFI (7 recipes)
• recipes/data-encoding.md - JSON, CSV, XML (9 recipes)
• recipes/iterators.md - Iterator patterns (8 recipes)
• recipes/webassembly.md - WASM targets (6 recipes)

Querying recipes programmatically:

# List all topics with counts
python scripts/query_recipes.py --list-topics

# Find recipes by topic
python scripts/query_recipes.py --topic memory-allocators

# Find recipes by tag
python scripts/query_recipes.py --tag hashmap

# Search by keyword
python scripts/query_recipes.py --search "error handling"

# Get specific recipe details
python scripts/query_recipes.py --recipe 1.1

# Filter by difficulty
python scripts/query_recipes.py --difficulty beginner

# JSON output for programmatic use
python scripts/query_recipes.py --topic data-structures --json

Recipe format: Each recipe includes Problem, Solution, Discussion sections plus full tested code.

When to use recipes vs references:

• Recipes: "How do I..." questions, practical tasks, working code examples
• References: "What is..." questions, API lookup, comprehensive documentation

Templates

Copy and customize these starting points:

• assets/templates/basic-program.zig - Basic program with allocator
• assets/templates/build.zig - Build configuration
• assets/templates/test.zig - Test file structure
• assets/templates/cli-application.zig - CLI app with arg parsing
• assets/templates/library-module.zig - Library/module structure
• assets/templates/c-interop-module.zig - C interop module

Examples

Complete, runnable code demonstrating patterns:

• examples/string_manipulation.zig - String processing
• examples/memory_management.zig - Allocator patterns
• examples/error_handling.zig - Error handling
• examples/c_interop.zig - C FFI
• examples/comptime_example.zig - Compile-time programming
• examples/build_example/ - Multi-file project

Scripts

Use these Python automation tools for version management, recipe queries, and code generation:

Version Detection & Reference Loading:

• scripts/get_references.py - Detect user's Zig version and return correct reference path (use this first)
• scripts/detect_version.py - Standalone version detection with confidence levels

Recipe Queries:

• scripts/query_recipes.py - Search and filter recipes by topic, tag, difficulty, or keyword

Code Generation:

• scripts/code_generator.py - Generate Zig code from JSON specifications

When to execute vs reference:

• Execute get_references.py at the start of any Zig task to determine the correct reference path
• Execute query_recipes.py when searching for practical code examples or solutions
• Reference other scripts only when the user explicitly requests code generation or version management tasks
• Most scripts are for skill maintenance, not routine usage

See scripts/README.md for complete script documentation.

Workflows

Writing New Code

1. Start from template - Copy appropriate template from assets/templates/
2. Check version - Default to Zig 0.15.2 unless specified
3. Handle errors explicitly - Use try, catch, or errdefer
4. Pass allocators - Never use global state, pass allocators as parameters
5. Add tests immediately - Write test blocks alongside implementation
6. Document public APIs - Use /// doc comments for exported functions

Debugging Compilation Errors

Zig-specific gotchas:

• Comptime type resolution → Use @TypeOf() inspection or add explicit casts
• Allocator lifetime issues → Verify defer cleanup order and errdefer on error paths
• Optional unwrapping → Use .? only when certain; prefer orelse or if unwrap for safety

Debug tools: std.debug.print() for inspection, -Doptimize=Debug for stack traces, zig test to isolate issues

Explaining Concepts

To teach Zig concepts effectively:

1. Load relevant reference - Start with the appropriate reference file for the topic
2. Show runnable code - Use complete examples from examples/ directory
3. Highlight uniqueness - Emphasize Zig's distinguishing features (explicit allocators, comptime, no hidden control flow)
4. Reference stdlib - Point to specific standard library functions when applicable

Version Awareness

Default to Zig 0.15.2 unless user specifies otherwise or detection determines a different version.

Version Detection Workflow

At the start of any Zig task, determine the user's version using this workflow:

1. Check for explicit specification:

• User stated version in current conversation ("I'm using Zig 0.13")
• CLAUDE.md project file contains Zig version specification
• build.zig.zon has minimum_zig_version field

2. Automated detection (recommended):

# Run get_references.py to detect version and get correct reference path
python scripts/get_references.py --json

This script:

• Runs scripts/detect_version.py to analyze the project
• Attempts zig version command (most reliable)
• Scans build.zig and .zig files for version markers
• Returns reference path and version info with confidence level
• Handles fallbacks automatically (e.g., 0.14.1 → use 0.15.2 refs)

3. Manual detection (if automated fails):

• Scan build.zig for API patterns:

- b.path(...) → 0.11+ - std.Build → 0.11+ - b.addExecutable(.{...}) → 0.11+ - b.addExecutable("name", "file") → pre-0.11

• Check .zig files for syntax markers:

- for (items, 0..) |item, i| → 0.13+ - async/await keywords → 0.9-0.10 (removed in 0.11)

• Load references/version-differences.md for full detection markers

4. Ask user if ambiguous:

• "I detected you might be using Zig 0.13+ based on your build.zig. Can you confirm your version?"
• Offer common versions: 0.15.2 (stable), 0.14.1, 0.13.0, master (development)

5. Default to 0.15.2:

• Use current stable if no detection succeeds
• Inform user: "Assuming Zig 0.15.2. Let me know if you're using a different version."

Loading Version-Specific References

After detecting version:

1. Use scripts/get_references.py to determine correct reference path
2. Load references from that version directory (e.g., references/v0.15.2/)
3. Always load references/version-differences.md (shared file) for migration guidance

Example workflow:

# Detect version and get reference path
REF_PATH=$(python scripts/get_references.py)
# REF_PATH is now "references/v0.15.2" or "references/latest"

# Load version-specific documentation
cat $REF_PATH/core-language.md
cat $REF_PATH/build-system.md

# Version differences is shared across all versions
cat references/version-differences.md

Handling fallbacks:

• If exact version not available (e.g., 0.14.1), script returns closest match (0.15.2) with warning
• Warnings indicate major differences (e.g., "for loop syntax differs from 0.13+")
• Always check fallback warnings to understand version compatibility

Critical Breaking Changes

Be aware of these major version differences when writing code:

• 0.11+: Async/await removed, new build.zig API (std.Build, b.path())
• 0.13+: Modern for loop syntax (for (items, 0..) |item, i|)
• 0.12-: Different for loop syntax (manual index variables)
• Pre-0.11: Legacy build API (std.build.Builder), different error sets

See references/version-differences.md for:

• Detailed migration guides (0.10→0.11, 0.12→0.13, 0.13→0.15)
• Error message translations
• Before/after code examples
• Breaking changes catalog

Handling Different Versions

When user specifies or detection determines a different version:

1. Run scripts/get_references.py --version <VERSION> to get correct reference path
2. Load references/version-differences.md for migration details
3. Use version-specific references from the returned path
4. Adapt code patterns to the user's version
5. Flag deprecated features if using older version
6. Recommend modern alternatives when possible

Best practice for cross-version code:

• Prefer feature detection over version checks: @hasDecl(std, "Build") instead of if (version >= 0.11)
• See references/latest/patterns-integration.md for @hasDecl/@hasField examples
• Document target version in code comments: // Target Zig Version: 0.15.2
• For cross-version templates, see assets/templates/cross-version/

Best Practices

Core Zig idioms:

1. Explicit error handling - Use try, catch, or error unions; never ignore errors
2. Defer cleanup - Use defer for cleanup, errdefer for error-path cleanup
3. Pass allocators - Never use global state; pass allocators explicitly as parameters
4. Leverage comptime - Use compile-time execution for generic programming
5. Write tests inline - Use test "description" {} blocks alongside implementation
6. Document public APIs - Add /// doc comments for exported functions
7. Handle optionals explicitly - Use orelse, .?, or if unwrapping
8. No hidden control flow - Zig has no hidden allocations, exceptions, or async