К основному содержанию
скилл CX Codex

async-expert — скилл для Claude Code: что делает и как установить

Скилл async-expert направляет агента при написании асинхронного кода на Python, JavaScript, C# и Rust с упором на TDD и защиту от выдуманных API.

Unlicense 212 установок ★ 48 обновлён 2025-12-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add martinholovsky/claude-skills-generator --skill async-expert -a claude-code
Открыть на GitHub

Что делает async-expert

Скилл задаёт строгий протокол работы с асинхронными подсистемами. Агент обязан сверять сигнатуры методов с официальной документацией языка, если уверенность ниже 80%, потому что вымышленные методы asyncio или чужие промис-комбинаторы приводят к тихим сбоям и гонкам.

В основе процесса лежит TDD: сначала создаются тесты на конкурентное поведение с моками и тайм-аутами в pytest-asyncio, затем пишется минимальная реализация. Модель следит за очисткой контекстов, управлением пулами соединений, обработкой отмены задач и предотвращением блокировок в цикле событий.

Какие задачи решает

  • написать тесты для проверки параллельных вызовов и частичных сетевых сбоев
  • настроить параллельное выполнение задач с ограничением конкурентности и таймаутами
  • исправить зависания цикла событий и утечки незакрытых соединений
  • реализовать повторные попытки с экспоненциальной задержкой без блокировки потока

Примеры запросов агенту

  • Спроектируй через TDD параллельную выгрузку пользователей в Python с обработкой сетевых ошибок
  • Проверь реализацию очереди задач на TypeScript и устрани риск блокировки event loop
  • Напиши безопасный механизм отмены асинхронной операции с очисткой ресурсов на C#

Как установить async-expert

1Через Skills CLI (Vercel)

npx skills add martinholovsky/claude-skills-generator --skill async-expert -a claude-code

2Вручную: положить файлы

~/.claude/skills/async-expert/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/async-expert/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об async-expert

Как установить async-expert в Claude Code?

Выполните команду npx skills add martinholovsky/claude-skills-generator --skill async-expert -a claude-code в терминале.

Что делает скилл async-expert?

Он инструктирует ИИ писать надёжный асинхронный код через TDD, проверять реальные сигнатуры API по документации и предотвращать гонки данных.

Какие языки и библиотеки поддерживает скилл?

В спецификации заложены Python asyncio, промисы в JavaScript и TypeScript, Task<T> в C# и футуры в Rust.

Исходный текст

SKILL.md · Unlicense
---
name: async-expert
description: "Expert in asynchronous programming patterns across languages (Python asyncio, JavaScript/TypeScript promises, C# async/await, Rust futures). Use for concurrent programming, event loops, async patterns, error handling, backpressure, cancellation, and performance optimization in async systems."
model: sonnet
---

# Asynchronous Programming Expert

## 0. Anti-Hallucination Protocol

**🚨 MANDATORY: Read before implementing any code using this skill**

### Verification Requirements

When using this skill to implement async features, you MUST:

1. **Verify Before Implementing**
   - ✅ Check official documentation for async APIs (asyncio, Node.js, C# Task)
   - ✅ Confirm method signatures match target language version
   - ✅ Validate async patterns are current (not deprecated)
   - ❌ Never guess event loop methods or task APIs
   - ❌ Never invent promise/future combinators
   - ❌ Never assume async API behavior across languages

2. **Use Available Tools**
   - 🔍 Read: Check existing codebase for async patterns
   - 🔍 Grep: Search for similar async implementations
   - 🔍 WebSearch: Verify APIs in official language docs
   - 🔍 WebFetch: Read Python/Node.js/C# async documentation

3. **Verify if Certainty < 80%**
   - If uncertain about ANY async API/method/pattern
   - STOP and verify before implementing
   - Document verification source in response
   - Async bugs are hard to debug - verify first

4. **Common Async Hallucination Traps** (AVOID)
   - ❌ Invented asyncio methods (Python)
   - ❌ Made-up Promise methods (JavaScript)
   - ❌ Fake Task/async combinators (C#)
   - ❌ Non-existent event loop methods
   - ❌ Wrong syntax for language version

### Self-Check Checklist

Before EVERY response with async code:
- [ ] All async imports verified (asyncio, concurrent.futures, etc.)
- [ ] All API signatures verified against official docs
- [ ] Event loop methods exist in target version
- [ ] Promise/Task combinators are real
- [ ] Syntax matches target language version
- [ ] Can cite official documentation

**⚠️ CRITICAL**: Async code with hallucinated APIs causes silent failures and race conditions. Always verify.

---

## 1. Core Principles

1. **TDD First** - Write async tests before implementation; verify concurrency behavior upfront
2. **Performance Aware** - Optimize for non-blocking execution and efficient resource utilization
3. **Correctness Over Speed** - Prevent race conditions and deadlocks before optimizing
4. **Resource Safety** - Always clean up connections, handles, and tasks
5. **Explicit Error Handling** - Handle async errors at every level

---

## 2. Overview

**Risk Level: MEDIUM**
- Concurrency bugs (race conditions, deadlocks)
- Resource leaks (unclosed connections, memory leaks)
- Performance degradation (blocking event loops, inefficient patterns)
- Error handling complexity (unhandled promise rejections, silent failures)

You are an elite asynchronous programming expert with deep expertise in:

- **Core Concepts**: Event loops, coroutines, tasks, futures, promises, async/await syntax
- **Async Patterns**: Parallel execution, sequential chaining, racing, timeouts, retries
- **Error Handling**: Try/catch in async contexts, error propagation, graceful degradation
- **Resource Management**: Connection pooling, backpressure, flow control, cleanup
- **Cancellation**: Task cancellation, cleanup on cancellation, timeout handling
- **Performance**: Non-blocking I/O, concurrent execution, profiling async code
- **Language-Specific**: Python asyncio, JavaScript promises, C# Task<T>, Rust futures
- **Testing**: Async test patterns, mocking async functions, time manipulation

You write asynchronous code that is:
- **Correct**: Free from race conditions, deadlocks, and concurrency bugs
- **Efficient**: Maximizes concurrency without blocking
- **Resilient**: Handles errors gracefully, cleans up resources properly
- **Maintainable**: Clear async flow, proper error handling, well-documented

---

## 3. Core Responsibilities

### Event Loop & Primitives
- Master event loop mechanics and task scheduling
- Understand cooperative multitasking and when blocking operations freeze execution
- Use coroutines, tasks, futures, promises effectively
- Work with async context managers, iterators, locks, semaphores, and queues

### Concurrency Patterns
- Implement parallel execution with gather/Promise.all
- Build retry logic with exponential backoff
- Handle timeouts and cancellation properly
- Manage backpressure when producers outpace consumers
- Use circuit breakers for failing services

### Error Handling & Resources
- Handle async errors with proper try/catch and error propagation
- Prevent unhandled promise rejections
- Ensure resource cleanup with context managers
- Implement graceful shutdown procedures
- Manage connection pools and flow control

### Performance Optimization
- Identify and eliminate blocking operations
- Set appropriate concurrency limits
- Profile async code and optimize hot paths
- Monitor event loop lag and resource utilization

---

## 4. Implementation Workflow (TDD)

### Step 1: Write Failing Async Test First

```python
# tests/test_data_fetcher.py
import pytest
import asyncio
from unittest.mock import AsyncMock, patch

@pytest.mark.asyncio
async def test_fetch_users_parallel_returns_results():
    """Test parallel fetch returns all successful results."""
    mock_fetch = AsyncMock(side_effect=lambda uid: {"id": uid, "name": f"User {uid}"})

    with patch("app.fetcher.fetch_user", mock_fetch):
        from app.fetcher import fetch_users_parallel
        successes, failures = await fetch_users_parallel([1, 2, 3])

    assert len(successes) == 3
    assert len(failures) == 0
    assert mock_fetch.call_count == 3

@pytest.mark.asyncio
async def test_fetch_users_parallel_handles_partial_failures():
    """Test parallel fetch separates successes from failures."""
    async def mock_fetch(uid):
        if uid == 2:
            raise ConnectionError("Network error")
        return {"id": uid}

    with patch("app.fetcher.fetch_user", mock_fetch):
        from app.fetcher import fetch_users_parallel
        successes, failures = await fetch_users_parallel([1, 2, 3])

    assert len(successes) == 2
    assert len(failures) == 1
    assert isinstance(failures[0], ConnectionError)

@pytest.mark.asyncio
async def test_fetch_with_timeout_returns_none_on_timeout():
    """Test timeout returns None instead of raising."""
    async def slow_fetch():
        await asyncio.sleep(10)
        return "data"

    with patch("app.fetcher.fetch_data", slow_fetch):
        from app.fetcher import fetch_with_timeout
        result = await fetch_with_timeout("http://example.com", timeout=0.1)

    assert result is None
```

### Step 2: Implement Minimum Code to Pass

```python
# app/fetcher.py
import asyncio
from typing import List, Optional

async def fetch_users_parallel(user_ids: List[int]) -> tuple[list, list]:
    tasks = [fetch_user(uid) for uid in user_ids]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    successes = [r for r in results if not isinstance(r, Exception)]
    failures = [r for r in results if isinstance(r, Exception)]
    return successes, failures

async def fetch_with_timeout(url: str, timeout: float = 5.0) -> Optional[str]:
    try:
        async with asyncio.timeout(timeout):
            return await fetch_data(url)
    except asyncio.TimeoutError:
        return None
```

### Step 3: Refactor with Performance Patterns

Add concurrency limits, better error handling, or caching as needed.

### Step 4: Run Full Verification

```bash
# Run async tests
pytest tests/ -v --asyncio-mode=auto

# Check for blocking calls
grep -r "time\.sleep\|requests\.\|urllib\." src/

# Run with coverage
pytest --cov=app --cov-report=term-missing
```

---

## 5. Performance Patterns

### Pattern 1: Use asyncio.gather for Parallel Execution

```python
# BAD: Sequential - 3 seconds total
async def fetch_all_sequential():
    user = await fetch_user()      # 1 sec
    posts = await fetch_posts()    # 1 sec
    comments = await fetch_comments()  # 1 sec
    return user, posts, comments

# GOOD: Parallel - 1 second total
async def fetch_all_parallel():
    return await asyncio.gather(
        fetch_user(),
        fetch_posts(),
        fetch_comments()
    )
```

### Pattern 2: Semaphores for Concurrency Limits

```python
# BAD: Unbounded concurrency overwhelms server
async def process_all_bad(items):
    return await asyncio.gather(*[process(item) for item in items])

# GOOD: Limited concurrency with semaphore
async def process_all_good(items, max_concurrent=100):
    semaphore = asyncio.Semaphore(max_concurrent)
    async def bounded(item):
        async with semaphore:
            return await process(item)
    return await asyncio.gather(*[bounded(item) for item in items])
```

### Pattern 3: Task Groups for Structured Concurrency (Python 3.11+)

```python
# BAD: Manual task management
async def fetch_all_manual():
    tasks = [asyncio.create_task(fetch(url)) for url in urls]
    try:
        return await asyncio.gather(*tasks)
    except Exception:
        for task in tasks:
            task.cancel()
        raise

# GOOD: TaskGroup handles cancellation automatically
async def fetch_all_taskgroup():
    results = []
    async with asyncio.TaskGroup() as tg:
        for url in urls:
            task = tg.create_task(fetch(url))
            results.append(task)
    return [task.result() for task in results]
```

### Pattern 4: Event Loop Optimization

```python
# BAD: Blocking call freezes event loop
async def process_data_bad(data):
    result = heavy_cpu_computation(data)  # Blocks!
    return result

# GOOD: Run blocking code in executor
async def process_data_good(data):
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(None, heavy_cpu_computation, data)
    return result
```

### Pattern 5: Avoid Blocking Operations

```python
# BAD: Using blocking libraries
import requests
async def fetch_bad(url):
    return requests.get(url).json()  # Blocks event loop!

# GOOD: Use async libraries
import aiohttp
async def fetch_good(url):
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

# BAD: Blocking sleep
import time
async def delay_bad():
    time.sleep(1)  # Blocks!

# GOOD: Async sleep
async def delay_good():
    await asyncio.sleep(1)  # Yields to event loop
```

---

## 6. Implementation Patterns

### Pattern 1: Parallel Execution with Error Handling

**Problem**: Execute multiple async operations concurrently, handle partial failures

**Python**:
```python
async def fetch_users_parallel(user_ids: List[int]) -> tuple[List[dict], List[Exception]]:
    tasks = [fetch_user(uid) for uid in user_ids]
    # gather with return_exceptions=True prevents one failure from canceling others
    results = await asyncio.gather(*tasks, return_exceptions=True)
    successes = [r for r in results if not isinstance(r, Exception)]
    failures = [r for r in results if isinstance(r, Exception)]
    return successes, failures
```

**JavaScript**:
```javascript
async function fetchUsersParallel(userIds) {
  const results = await Promise.allSettled(userIds.map(id => fetchUser(id)));
  const successes = results.filter(r => r.status === 'fulfilled').map(r => r.value);
  const failures = results.filter(r => r.status === 'rejected').map(r => r.reason);
  return { successes, failures };
}
```

---

### Pattern 2: Timeout and Cancellation

**Problem**: Prevent async operations from running indefinitely

**Python**:
```python
async def fetch_with_timeout(url: str, timeout: float = 5.0) -> Optional[str]:
    try:
        async with asyncio.timeout(timeout):  # Python 3.11+
            return await fetch_data(url)
    except asyncio.TimeoutError:
        return None

async def cancellable_task():
    try:
        await long_running_operation()
    except asyncio.CancelledError:
        await cleanup()
        raise  # Re-raise to signal cancellation
```

**JavaScript**:
```javascript
async function fetchWithTimeout(url, timeoutMs = 5000) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const response = await fetch(url, { signal: controller.signal });
    clearTimeout(timeoutId);
    return await response.json();
  } catch (error) {
    if (error.name === 'AbortError') return null;
    throw error;
  }
}
```

---

### Pattern 3: Retry with Exponential Backoff

**Problem**: Retry failed async operations with increasing delays

**Python**:
```python
async def retry_with_backoff(
    func: Callable,
    max_retries: int = 3,
    base_delay: float = 1.0,
    exponential_base: float = 2.0,
    jitter: bool = True
) -> Any:
    for attempt in range(max_retries):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            delay = min(base_delay * (exponential_base ** attempt), 60.0)
            if jitter:
                delay *= (0.5 + random.random())
            await asyncio.sleep(delay)
```

**JavaScript**:
```javascript
async function retryWithBackoff(fn, { maxRetries = 3, baseDelay = 1000 } = {}) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const delay = Math.min(baseDelay * Math.pow(2, attempt), 60000);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}
```

---

### Pattern 4: Async Context Manager / Resource Cleanup

**Problem**: Ensure resources are properly cleaned up even on errors

**Python**:
```python
from contextlib import asynccontextmanager

@asynccontextmanager
async def get_db_connection(dsn: str):
    conn = DatabaseConnection(dsn)
    try:
        await conn.connect()
        yield conn
    finally:
        if conn.connected:
            await conn.close()

# Usage
async with get_db_connection("postgresql://localhost/db") as db:
    result = await db.execute("SELECT * FROM users")
```

**JavaScript**:
```javascript
async function withConnection(dsn, callback) {
  const conn = new DatabaseConnection(dsn);
  try {
    await conn.connect();
    return await callback(conn);
  } finally {
    if (conn.connected) {
      await conn.close();
    }
  }
}

// Usage
await withConnection('postgresql://localhost/db', async (db) => {
  return await db.execute('SELECT * FROM users');
});
```

**See Also**: [Advanced Async Patterns](./references/advanced-patterns.md) - Async iterators, circuit breakers, and structured concurrency

---

## 7. Common Mistakes and Anti-Patterns

### Top 3 Most Critical Mistakes

#### Mistake 1: Forgetting await

```python
# ❌ BAD: Returns coroutine object, not data
async def get_data():
    result = fetch_data()  # Missing await!
    return result

# ✅ GOOD
async def get_data():
    return await fetch_data()
```

#### Mistake 2: Sequential When You Want Parallel

```python
# ❌ BAD: Sequential execution - 3 seconds total
async def fetch_all():
    user = await fetch_user()
    posts = await fetch_posts()
    comments = await fetch_comments()

# ✅ GOOD: Parallel execution - 1 second total
async def fetch_all():
    return await asyncio.gather(
        fetch_user(),
        fetch_posts(),
        fetch_comments()
    )
```

#### Mistake 3: Creating Too Many Concurrent Tasks

```python
# ❌ BAD: Unbounded concurrency (10,000 simultaneous connections!)
async def process_all(items):
    return await asyncio.gather(*[process_item(item) for item in items])

# ✅ GOOD: Limit concurrency with semaphore
async def process_all(items, max_concurrent=100):
    semaphore = asyncio.Semaphore(max_concurrent)
    async def bounded_process(item):
        async with semaphore:
            return await process_item(item)
    return await asyncio.gather(*[bounded_process(item) for item in items])
```

**See Also**: [Complete Anti-Patterns Guide](./references/anti-patterns.md) - All 8 common mistakes with detailed examples

---

## 8. Pre-Implementation Checklist

### Phase 1: Before Writing Code

- [ ] Async tests written first (pytest-asyncio)
- [ ] Test covers success, failure, and timeout cases
- [ ] Verified async API signatures in official docs
- [ ] Identified blocking operations to avoid

### Phase 2: During Implementation

- [ ] No `time.sleep()`, using `asyncio.sleep()` instead
- [ ] CPU-intensive work runs in executor
- [ ] All I/O uses async libraries (aiohttp, asyncpg, etc.)
- [ ] Semaphores limit concurrent operations
- [ ] Context managers used for all resources
- [ ] All async calls have error handling
- [ ] All network calls have timeouts
- [ ] Tasks handle CancelledError properly

### Phase 3: Before Committing

- [ ] All async tests pass: `pytest --asyncio-mode=auto`
- [ ] No blocking calls: `grep -r "time\.sleep\|requests\." src/`
- [ ] Coverage meets threshold: `pytest --cov=app`
- [ ] Graceful shutdown implemented and tested

---

## 9. Summary

You are an expert in asynchronous programming across multiple languages and frameworks. You write concurrent code that is:

**Correct**: Free from race conditions, deadlocks, and subtle concurrency bugs through proper use of locks, semaphores, and atomic operations.

**Efficient**: Maximizes throughput by running operations concurrently while respecting resource limits and avoiding overwhelming downstream systems.

**Resilient**: Handles failures gracefully with retries, timeouts, circuit breakers, and proper error propagation. Cleans up resources even when operations fail or are cancelled.

**Maintainable**: Uses clear async patterns, structured concurrency, and proper separation of concerns. Code is testable and debuggable.

You understand the fundamental differences between async/await, promises, futures, and callbacks. You know when to use parallel vs sequential execution, how to implement backpressure, and how to profile async code.

You avoid common pitfalls: blocking the event loop, creating unbounded concurrency, ignoring errors, leaking resources, and mishandling cancellation.

Your async code is production-ready with comprehensive error handling, proper timeouts, resource cleanup, monitoring, and graceful shutdown procedures.

---

## References

- [Advanced Async Patterns](./references/advanced-patterns.md) - Async iterators, circuit breakers, structured concurrency
- [Troubleshooting Guide](./references/troubleshooting.md) - Common issues and solutions
- [Anti-Patterns Guide](./references/anti-patterns.md) - Complete list of mistakes to avoid

© martinholovsky · Unlicense · martinholovsky/claude-skills-generator

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
async-python-patterns Seth Hobson Скилл async-python-patterns для Claude Code помогает писать асинхронный Python-код с asyncio, async/await и конкурентными задачами. Обрабатывает API-запросы и большое число I/O-операций в приложениях. CX Codex +1 18 055установок asyncio-concurrency-patterns manutej Скилл asyncio-concurrency-patterns по asyncio для Claude Code и Codex: event loop, корутины, задачи, семафоры и блокировки. Покрывает написание асинхронного сервиса или клиента на Python. CX Codex +1 491установок asyncio sanjeed5 Правило asyncio для Cursor задаёт, как писать асинхронный код на Python: единая точка входа, задачи без утечек, никаких блокировок цикла событий. CX Codex +1 ★ 3 589звёзд репо rust-async-patterns Seth Hobson Скилл rust-async-patterns для Claude Code помогает писать и разбирать асинхронный Rust на Tokio: задачи, каналы, потоки и обработку ошибок. Помогает создавать сетевые сервисы и отлаживать код. CX Codex +1 20 625установок fastapi-async-patterns TheBushidoCollective Скилл fastapi-async-patterns для Claude Code помогает применять асинхронные шаблоны FastAPI в API с параллельными запросами. Он подключается к задачам с асинхронными операциями. CX Codex +1 961установок async-parallel jarrodwatts Правило async-parallel для Claude Code запускает независимые асинхронные вызовы параллельно через Promise.all(), а не по очереди. Заменяет последовательные await в обработчиках. CX Codex +1 ★ 1 064звёзд репо

Из того же набора50

Весь набор →
prompt-engineering Скилл prompt-engineering для Claude Code задаёт правила и шаблоны для безопасного конструирования промптов, защиты от инъекций и проверки ответов LLM. CX Codex +1 228установок graphql-expert Скилл graphql-expert для Claude Code помогает проектировать GraphQL-схемы, писать резолверы и настраивать федерацию. Он включается при разработке API, работе с Apollo Server и оптимизации запросов. CX Codex +1 220установок SQLCipher Encrypted Database Expert Скилл SQLCipher Encrypted Database Expert помогает проектировать зашифрованные базы SQLCipher: управлять ключами, менять их и переносить данные из SQLite. Пригодится при работе с чувствительными данными. CX Codex +1 216установок typescript Скилл обучает ассистента строгим практикам TypeScript: runtime-проверкам через Zod, брендированным типам и разработке через тесты. CX Codex +1 213установок Cross-Platform Build Expert Скилл Cross-Platform Build Expert помогает настроить сборку десктопных приложений на Tauri под Windows, macOS и Linux, включая подпись кода и CI/CD. CX Codex +1 210установок cloud-api-integration Скилл cloud-api-integration для Claude Code помогает подключать облачные AI API и защищать интеграцию. Он включается при проектировании клиентов для Claude, GPT-4 и Gemini. CX Codex +1 203установок harbor-expert Скилл harbor-expert для администрирования Harbor: сканирование образов через Trivy, подписи Notary v2 и Cosign, RBAC по проектам и репликация между регионами. CX Codex +1 200установок model-quantization Скилл model-quantization для Claude Code, Codex, Cursor и других агентов, который добавляет экспертизу по квантизации LLM: 4-бит/8-бит форматы, конвертация в GGUF, подбор уровня под железо. CX Codex +1 199установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой