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

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

Скилл llm-debugger находит причины сбоев в ответах нейросетей, правит системные промпты и генерирует регрессионные тесты для фиксации ошибок.

MIT 259 установок ★ 64 обновлён 2026-01-12

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

Что делает llm-debugger

Скилл анализирует ответы языковых моделей по таксономии сбоев. Он классифицирует проблемы на галлюцинации, невалидный формат вроде сломанного JSON, нарушение лимита длины, ошибки в цепочке рассуждений и сбои при вызове инструментов.

После разбора исходного запроса и ответа скилл предлагает готовые правки в промпт. Он добавляет требование заземления на контекст, пошаговый вывод или чёткую схему структуры. Для инструментов скилл дополняет схемы описанием обязательных параметров и рабочими примерами.

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

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

  • Найти причину поломки JSON и пропущенных полей в ответе модели
  • Добавить в системный промпт инструкции против галлюцинаций
  • Исправить схему параметров инструмента при некорректных вызовах
  • Сгенерировать регрессионные тесты для проверки исправленного промпта

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

  • Разбери, почему модель выдала некорректный JSON вместо схемы, и поправь промпт
  • Проверь ответ на галлюцинации и составь тесты для регрессии

Как установить llm-debugger

1Через Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill llm-debugger -a claude-code

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

~/.claude/skills/llm-debugger/SKILL.md

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

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

Вопросы о llm-debugger

Как установить llm-debugger в Claude Code?

Выполните в терминале команду npx skills add patricio0312rev/skills --skill llm-debugger -a claude-code. Файл навыка сохранится в ~/.claude/skills/llm-debugger/SKILL.md.

Какие сбои классифицирует скилл?

Он выявляет галлюцинации, ошибки форматирования, пропуск обязательных полей, превышение ограничений по длине, логические сбои и некорректный вызов инструментов.

Что нужно передать скиллу для точной диагностики?

Понадобятся исходный промпт, полученный сбойный ответ и ожидаемые требования к результату вроде формата или обязательных полей.

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

SKILL.md · MIT
---
name: llm-debugger
description: Diagnoses LLM output failures including hallucinations, constraint violations, format errors, and reasoning issues. Provides root cause classification, prompt fixes, tool improvements, and new test cases. Use for "debugging AI", "fixing prompts", "quality issues", or "output errors".
---

# LLM Debugger

Systematically diagnose and fix LLM output issues.

## Failure Taxonomy

```python
class FailureType(Enum):
    HALLUCINATION = "hallucination"
    FORMAT_VIOLATION = "format_violation"
    CONSTRAINT_BREAK = "constraint_break"
    REASONING_ERROR = "reasoning_error"
    TOOL_MISUSE = "tool_misuse"
    REFUSAL = "unexpected_refusal"
    INCOMPLETE = "incomplete_output"
```

## Root Cause Analysis

```python
def diagnose_failure(input: str, output: str, expected: dict) -> dict:
    """Identify why LLM output failed"""

    issues = []

    # Check format
    if expected.get("format") == "json":
        try:
            json.loads(output)
        except:
            issues.append({
                "type": FailureType.FORMAT_VIOLATION,
                "details": "Invalid JSON output"
            })

    # Check required fields
    if expected.get("required_fields"):
        for field in expected["required_fields"]:
            if field not in output:
                issues.append({
                    "type": FailureType.INCOMPLETE,
                    "details": f"Missing required field: {field}"
                })

    # Check constraints
    if expected.get("max_length"):
        if len(output) > expected["max_length"]:
            issues.append({
                "type": FailureType.CONSTRAINT_BREAK,
                "details": f"Output too long: {len(output)} > {expected['max_length']}"
            })

    # Check for hallucination indicators
    if contains_hallucination_markers(output):
        issues.append({
            "type": FailureType.HALLUCINATION,
            "details": "Contains fabricated information"
        })

    return {
        "has_issues": len(issues) > 0,
        "issues": issues,
        "primary_issue": issues[0] if issues else None
    }

def contains_hallucination_markers(output: str) -> bool:
    """Detect common hallucination patterns"""
    markers = [
        r'According to.*that doesn\'t exist',
        r'In \d{4}.*before that year',
        r'contradicts itself',
    ]
    return any(re.search(marker, output, re.IGNORECASE) for marker in markers)
```

## Prompt Fixes

````python
PROMPT_FIXES = {
    FailureType.FORMAT_VIOLATION: """
Add strict format instructions:
"Output MUST be valid JSON with this exact structure:
```json
{{"field1": "value", "field2": 123}}
````

Do not add any text before or after the JSON."
""",

    FailureType.HALLUCINATION: """

Add grounding instructions:
"Base your response ONLY on the provided context.
If information is not in the context, say 'I don't have that information.'
Never make up facts or details."
""",

    FailureType.CONSTRAINT_BREAK: """

Add explicit constraints:
"Your response must be:

- Maximum 200 words
- No code examples
- Professional tone only"
  """,
      FailureType.REASONING_ERROR: """
  Add step-by-step reasoning:
  "Think through this step by step:

1. First, identify...
2. Then, consider...
3. Finally, conclude..."
   """,
   }

def suggest_prompt_fix(diagnosis: dict, current_prompt: str) -> str:
"""Generate improved prompt based on diagnosis"""
primary_issue = diagnosis["primary_issue"]
if not primary_issue:
return current_prompt

    fix = PROMPT_FIXES[primary_issue["type"]]

    return f"""{current_prompt}

IMPORTANT INSTRUCTIONS:
{fix}
"""

````

## Tool Improvements

```python
def suggest_tool_fixes(diagnosis: dict, tool_schema: dict) -> dict:
    """Improve tool schema to prevent misuse"""

    fixes = {}

    for issue in diagnosis["issues"]:
        if issue["type"] == FailureType.TOOL_MISUSE:
            # Make required parameters more explicit
            fixes["parameters"] = {
                **tool_schema["parameters"],
                "description": "REQUIRED: " + tool_schema["parameters"].get("description", "")
            }

            # Add examples
            fixes["examples"] = [
                {
                    "params": {"query": "example search"},
                    "description": "Use for finding information"
                }
            ]

    return {**tool_schema, **fixes}
````

## Test Case Generation

```python
def generate_test_cases(diagnosis: dict, failed_input: str, failed_output: str) -> List[dict]:
    """Create regression test cases from failures"""

    test_cases = []

    # Test case for the specific failure
    test_cases.append({
        "input": failed_input,
        "expected_behavior": "Should not " + diagnosis["primary_issue"]["details"],
        "validation": lambda output: not has_same_issue(output, diagnosis),
    })

    # Edge cases based on failure type
    if diagnosis["primary_issue"]["type"] == FailureType.FORMAT_VIOLATION:
        test_cases.append({
            "input": failed_input,
            "validation": lambda output: is_valid_json(output),
            "description": "Output must be valid JSON"
        })

    # Similar inputs that might trigger same issue
    similar_inputs = generate_similar_inputs(failed_input)
    for inp in similar_inputs:
        test_cases.append({
            "input": inp,
            "validation": lambda output: not has_same_issue(output, diagnosis),
        })

    return test_cases
```

## Debugging Workflow

```python
def debug_llm_output(
    prompt: str,
    output: str,
    expected: dict,
    context: dict = {}
) -> dict:
    """Complete debugging workflow"""

    # 1. Diagnose issue
    diagnosis = diagnose_failure(prompt, output, expected)

    if not diagnosis["has_issues"]:
        return {"status": "ok", "diagnosis": diagnosis}

    # 2. Generate fixes
    fixed_prompt = suggest_prompt_fix(diagnosis, prompt)

    # 3. Create test cases
    test_cases = generate_test_cases(diagnosis, prompt, output)

    # 4. Test fix
    test_output = llm(fixed_prompt)
    fix_works = diagnose_failure(fixed_prompt, test_output, expected)["has_issues"] == False

    return {
        "status": "issues_found",
        "diagnosis": diagnosis,
        "fixes": {
            "prompt": fixed_prompt,
            "fix_verified": fix_works,
        },
        "test_cases": test_cases,
        "recommendations": generate_recommendations(diagnosis, context)
    }
```

## Interactive Debugging

```python
def interactive_debug():
    """Interactive debugging session"""
    print("LLM Debugger - Interactive Mode")

    prompt = input("Enter prompt: ")
    expected_output = input("Expected output format (json/text): ")

    output = llm(prompt)
    print(f"\nGenerated output:\n{output}\n")

    if input("Does this look correct? (y/n): ").lower() == 'n':
        diagnosis = diagnose_failure(prompt, output, {"format": expected_output})

        print("\nDiagnosis:")
        for issue in diagnosis["issues"]:
            print(f"- {issue['type'].value}: {issue['details']}")

        print("\nSuggested fix:")
        print(suggest_prompt_fix(diagnosis, prompt))
```

## Best Practices

1. **Reproduce consistently**: Multiple runs
2. **Isolate variables**: Test prompt changes one at a time
3. **Check examples**: Are few-shot examples clear?
4. **Validate constraints**: Are they explicit enough?
5. **Test edge cases**: Boundary conditions
6. **Log everything**: Inputs, outputs, issues
7. **Iterate systematically**: Track what fixes work

## Output Checklist

- [ ] Failure taxonomy defined
- [ ] Root cause analyzer
- [ ] Prompt fix suggestions
- [ ] Tool schema improvements
- [ ] Test case generator
- [ ] Fix verification
- [ ] Debugging workflow
- [ ] Recommendations engine
- [ ] Interactive debugger
- [ ] Logging system

© patricio0312rev · MIT · patricio0312rev/skills

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

Все скиллы по теме «ИИ и ML» →
debugger zhaono1 Скилл debugger ведёт агента по методике отладки: воспроизвести баг, сузить область, найти причину, починить и закрыть регрессионным тестом. CX Codex +1 756установок exploring-llm-traces PostHog Скилл exploring-llm-traces для Claude Code разбирает трассы LLM-агентов через инструменты PostHog MCP. Запускается по ссылке на трассу или сессию, а также при вопросах об ошибках, инструментах, контексте и расходе токенов. CX Codex +1 440установок llm-document-extraction datadrivenconstruction Скилл llm-document-extraction превращает неструктурированные PDF-документы (РФИ, сметы, контракты, спецификации) в структурированные JSON и Excel. Использует LLM для анализа текста и автоматической классификации данных. CX Codex +1 125установок ia-qa mcp llm and RAG testing - Dev/QA toolbox ia-qa ia-qa mcp llm and RAG testing - Dev/QA toolbox — MCP-сервер для Claude Code, который проверяет LLM, RAG и задачи Dev/QA: считает токены и стоимость запросов, делит текст на чанки и сравнивает промпты. CX Codex +1 12 266установок llm-patterns alinaqi Скилл llm-patterns для Claude Code задаёт архитектуру AI-first приложений: типизацию вызовов, версионирование промптов и тестирование. CX Codex +1 302установок testing-llm OrchestKit Скилл testing-llm помогает тестировать функции с языковыми моделями: подменять ответы, оценивать качество RAG и проверять структурированный вывод. Включается при разработке тестов для ИИ-функций. CX Codex +1 126установок

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

Весь набор →
db-performance-watchlist Скилл db-performance-watchlist для Claude Code отслеживает метрики PostgreSQL: медленные запросы, пул соединений и неиспользуемые индексы через Prisma. CX Codex +1 260установок api-contract-normalizer Скилл api-contract-normalizer для Claude Code приводит ответы API к общим правилам формата, ошибок, пагинации и версий. Унифицирует ответы разных эндпоинтов. CX Codex +1 260установок vscode-rest-client-generator Скилл vscode-rest-client-generator для Claude Code находит маршруты в Express, Next.js и Fastify и генерирует .http-файлы для VS Code REST Client. Файлы содержат запросы для ручного тестирования API в редакторе без Postman. CX Codex +1 259установок embedding-pipeline-builder Скилл embedding-pipeline-builder для Claude Code собирает пайплайны эмбеддингов документов: загрузку, очистку, чанкинг, индексацию и настройку поиска. Поддерживает RAG и семантическую индексацию. CX Codex +1 259установок tool-function-schema-designer Скилл tool-function-schema-designer помогает описать инструменты для LLM так, чтобы модель вызывала их с валидными аргументами: JSON-схема, типы, проверка через zod и примеры вызовов. CX Codex +1 258установок test-reporting-triage-skill Скилл test-reporting-triage-skill для Claude Code группирует ошибки тестов по категориям, предлагает ответственные команды и варианты исправления. Разбирает результаты прогона тестов. CX Codex +1 257установок mocking-assistant Скилл mocking-assistant помогает создавать моки для API, сервисов и UI через MSW и Vitest: от фикстур данных до перехвата системного времени в тестах. CX Codex +1 256установок service-layer-extractor Скилл service-layer-extractor выносит бизнес-логику из контроллеров в сервисы и репозитории. Помогает навести порядок в раздутых роутах и подготовить код к юнит-тестам. CX Codex +1 255установок

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

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