Ailang Code Writing

AILANG Code Writing

Write correct AILANG code following current syntax (v0.3.12+).

Quick Start

AILANG is a pure functional programming language with Hindley-Milner type inference and algebraic effects.

Most common usage:

ailang run --caps IO --entry main solution.ail   # Run with effects
ailang repl                                        # Interactive development
ailang check solution.ail                          # Type-check only
ailang verify solution.ail                         # Prove contracts with Z3

When to Use This Skill

Invoke this skill when:

• User asks to write AILANG code
• User needs help with AILANG syntax errors
• User wants to run AILANG programs
• User asks about AILANG features or capabilities
• User mentions AILANG version or syntax
• User wants to add verification or contracts to AILANG code
• User asks about Z3, SMT, or formal verification in AILANG

Available Scripts

scripts/check_version.sh

Check current active AILANG prompt version from prompts/versions.json.

Usage:

.claude/skills/use-ailang/scripts/check_version.sh

Output:

Active AILANG version: v0.3.12
Prompt file: prompts/v0.3.12.md
Status: File exists ✓

scripts/validate_code.sh <file.ail>

Validate AILANG code syntax using ailang check.

Usage:

.claude/skills/use-ailang/scripts/validate_code.sh solution.ail

Output:

Validating solution.ail...
✓ Type check passed

Key Resources

1. Current Version Check (Always Use First!)

# Check active prompt version
.claude/skills/use-ailang/scripts/check_version.sh

The active version in prompts/versions.json is the source of truth for current AILANG syntax.

2. Syntax Quick Reference

See resources/syntax_quick_ref.md for:

• Basic syntax rules (func, semicolons, patterns)
• Core language features (functions, ADTs, records, effects)
• Standard library overview
• What works vs what doesn't work

3. Common Patterns

See resources/common_patterns.md for:

• Recursion patterns (no loops!)
• Pattern matching examples
• Effects and IO patterns
• Record updates
• Common mistakes and fixes
• Best practices

4. Z3 Verification Patterns

See resources/z3_verification_patterns.md for:

• "Pure core, effectful shell" architecture
• Writing contracts (requires/ensures)
• The decidable fragment (what Z3 can and cannot verify)
• Refactoring effectful code for verification
• Running ailang verify

5. Searchable Examples (v0.6.2+)

Use CLI to find working AILANG patterns:

ailang examples search "pattern matching"   # Search by content/tags
ailang examples show adt_option             # View example with metadata
ailang examples list --tags recursion       # Filter by tag
ailang examples tags                        # List all available tags

6. Dev Tools Reference (v0.8.0+)

Run ailang devtools-prompt for toolchain documentation covering:

• Debugging with traces, replay, determinism verification
• Agent chains, coordinator, messaging
• Eval harness, telemetry, compilation

7. Full Documentation

• Teaching prompt: ailang prompt (language syntax)
• Dev tools prompt: ailang devtools-prompt (toolchain usage)
• Website: https://ailang.sunholo.com/
• Examples: examples/runnable/ directory (96 working examples)
• REPL commands: docs/docs/reference/repl-commands.md

Usage Contexts

1. REPL (Interactive Development)

Most flexible - No module declaration needed:

ailang repl

> 5 + 3
8 : int

> let double = func(x: int) -> int { x * 2 }
> double(21)
42 : int

> :type double
func(int) -> int

2. Module Files (General Programs)

Standard usage - Module with exported functions:

module myapp/main

import std/io (println)

export func main() -> () ! {IO} {
  println("Hello, AILANG!")
}

# Run with effects (flags BEFORE filename!)
ailang run --caps IO main.ail

# Type-check only
ailang check main.ail

3. Eval Harness (AI Benchmarks)

Specific structure required - Must use module benchmark/solution:

module benchmark/solution

import std/io (println)

export func main() -> () ! {IO} {
  println("Benchmark solution")
}

Note: Teaching prompts in prompts/ use eval harness conventions for AI code generation benchmarks.

AILANG CLI Reference

Core Commands

# Interactive REPL
ailang repl

# Run a program (flags BEFORE filename!)
ailang run --caps IO,FS --entry main file.ail

# Type-check without running
ailang check file.ail

# Verify contracts with Z3
ailang verify file.ail
ailang verify --verbose file.ail              # Show generated SMT-LIB
ailang verify --json file.ail                 # Machine-readable output
ailang verify --verify-recursive-depth 5 file.ail  # Bounded recursion depth

# Watch for changes and auto-reload
ailang watch file.ail

# Output module interface (JSON)
ailang iface mymodule

# Export training data
ailang export-training

Run Command Flags

IMPORTANT: Flags must come BEFORE the filename!

# ✅ CORRECT
ailang run --caps IO,FS --entry main file.ail

# ❌ WRONG
ailang run file.ail --caps IO  # Flags ignored!

Available flags:

• --caps <list> - Enable capabilities (IO, FS, Net, Clock)
• --entry <name> - Entrypoint function (default: main)
• --args-json <json> - JSON arguments to pass to entrypoint
• --trace - Enable execution tracing
• --print - Print return value (default: true)
• --no-print - Suppress output (exit code only)

Development Commands

# Validate builtin registry
ailang doctor builtins

# List all builtins
ailang builtins list --by-module

# Run tests
ailang test

Examples Commands (v0.6.2+)

# Search for working examples
ailang examples search "pattern matching"
ailang examples search "recursion" --limit 5

# List examples with filters
ailang examples list                    # All working examples
ailang examples list --tags adt         # Filter by tag
ailang examples list --status all       # Include broken

# View specific example
ailang examples show adt_option         # Show with metadata
ailang examples show adt_option --run   # Show and execute
ailang examples show fold --expected    # Show expected output only

# List available tags
ailang examples tags

Progressive Disclosure

This skill loads information progressively:

1. Always loaded: This SKILL.md file (YAML frontmatter + overview)
2. Load on demand: resources/syntax_quick_ref.md (detailed syntax)
3. Load on demand: resources/common_patterns.md (examples and patterns)
4. Load on demand: resources/z3_verification_patterns.md (contracts and verification)
5. Execute as needed: Scripts in scripts/ directory

This saves context tokens while providing access to comprehensive information when needed.

Version Information

Current active version: Check with scripts/check_version.sh

As of this skill: v0.3.12 (October 2025)

Key features by version:

• v0.3.12: Emphasis on show() function (recovery release)
• v0.3.9: JSON encoding, HTTP headers for AI API integration
• v0.3.8: Multi-line ADTs, record updates, auto-import prelude
• v0.3.7: Effect system with capability security
• v0.3.5: Anonymous functions, letrec, numeric conversions

Check CHANGELOG.md for detailed version history.

Installation (For Reference)

# From releases (recommended)
wget https://github.com/sunholo-data/ailang/releases/latest/download/ailang-<platform>.tar.gz
tar xzf ailang-<platform>.tar.gz
sudo mv ailang /usr/local/bin/

# Or build from source
git clone https://github.com/sunholo-data/ailang
cd ailang
make install

Getting Help

• Version check: .claude/skills/use-ailang/scripts/check_version.sh
• Syntax reference: resources/syntax_quick_ref.md
• Common patterns: resources/common_patterns.md
• Teaching prompt: ailang prompt (language syntax from prompts/versions.json)
• Dev tools prompt: ailang devtools-prompt (toolchain: debug, trace, eval, chains)
• Documentation: https://ailang.sunholo.com/
• Examples: examples/ directory
• Issues: https://github.com/sunholo-data/ailang/issues
• REPL help: Type :help in the REPL

Workflow

When user asks for AILANG code:

1. Check version (optional, if uncertain):

   .claude/skills/use-ailang/scripts/check_version.sh
   

2. Load syntax reference (if needed): Read resources/syntax_quick_ref.md for detailed syntax rules

3. Load common patterns (if needed): Read resources/common_patterns.md for examples and best practices

4. Write code following current syntax

   • Prefer pure functions (! {}) for core logic — these are Z3-verifiable
   • Keep effectful code (! {IO}) as thin wrappers around pure functions

5. Add contracts to pure functions (if applicable): Read resources/z3_verification_patterns.md for contract patterns

6. Verify contracts (if contracts present):

   ailang verify solution.ail
   

7. Validate code (optional):

   .claude/skills/use-ailang/scripts/validate_code.sh solution.ail
   

8. Help user run with correct CLI flags

Notes

• This skill follows Anthropic's Agent Skills specification (Oct 2025)
• Uses progressive disclosure to save context tokens
• Scripts execute without loading into context window
• Resource files loaded on demand when detailed reference needed
• Always check prompts/versions.json for latest active version when writing benchmark code

Converted and distributed by TomeVault — claim your Tome and manage your conversions.