AL debugging and diagnostics for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection.

MITAuto-check passedDevelopment

Install Skill Debug

skills CLI
$ npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install javiarmesto/ALDC-AL-Development-Collection skill-debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/javiarmesto/ALDC-AL-Development-Collection.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/skill-debug .claude/skills/skill-debug && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
skill-debug
GitHub stars
109
Token cost
~2.5k tokens
SKILL.md length
714 words
Files
1
Skills in repo
14
Repo updated
First seen
Licence
MIT

At a glance

AL debugging and diagnostics for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection.

  • Works in 4 steps: Context Gathering (MANDATORY before any… → Diagnose Root Cause → Document Diagnosis (MANDATORY) → …
  • Performing snapshot debugging
  • SKILL.md covers Purpose, When to Load, Core Patterns and Workflow, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Skill Debug is an agent skill from javiarmesto/ALDC-AL-Development-Collection. AL debugging and diagnostics for Business Central. Use when performing snapshot debugging, CPU profiling, analyzing telemetry, or troubleshooting runtime issues.

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Debugging. The repository describes itself as: AL development toolkit for Business Central with specialist agents, skills and review workflows for Copilot, Claude Code and Codex. The licence is MIT.

When your agent uses it

  • Performing snapshot debugging
  • Analyzing telemetry
  • Troubleshooting runtime issues

Example prompts

  • “/skill-debug”

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Context Gathering (MANDATORY before any debugging)
  2. Diagnose Root Cause
  3. Document Diagnosis (MANDATORY)
  4. Propose Fix & Handoff (MANDATORY HITL gate)

What it can do on your machine

Read from SKILL.md and the folder at commit 161c3e3. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are al and markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • learn.microsoft.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Skill Debug loads about 2.5k tokens when it runs. Until then it costs about 43 tokens; SKILL.md has 714 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~43
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from javiarmesto/ALDC-AL-Development-Collection at commit 161c3e3, republished under its MIT licence (© javiarmesto). 714 words, ~2,467 tokens.

Download SKILL.mdSave it as .claude/skills/skill-debug/SKILL.md (or your agent's skills folder).
name
skill-debug
description
AL debugging and diagnostics for Business Central. Use when performing snapshot debugging, CPU profiling, analyzing telemetry, or troubleshooting runtime issues.

Skill: AL Debugging & Diagnostics

Purpose

For BC29 AL0926 section-order errors or new isolation behavior, read the relevant sections of AL18 capability checks. Use actual compiler/runtime evidence and keep compilation distinct from execution.

Systematic diagnosis and root cause analysis for AL Business Central issues: runtime errors, logic bugs, intermittent failures, performance bottlenecks, and configuration problems.

When to Load

This skill should be loaded when:

  • A runtime error, exception, or unexpected behavior is reported
  • A logic bug needs root cause analysis (not just a symptom fix)
  • An intermittent issue needs snapshot capture
  • A performance bottleneck needs CPU profiling
  • Configuration issues (auth, symbols, build, publishing) block development
  • An event subscriber is not firing as expected

Core Patterns

Pattern 1: Choose Debugging Strategy

Select the right tool before starting:

Issue TypeStrategyTool
Consistent runtime errorStandard debuggeral_debug
Already deployed codeDebug without publishal_debug
Rapid dev cycleIncremental publishal_publish (incremental)
Intermittent / hard-to-reproduceSnapshot debuggingal_snapshotdebugging
Slow performanceCPU profilingVS Code command (not an agent tool)
Auth / symbols / buildConfiguration troubleshootSee Workflow Step 2b
Copilot AI featureAgent session debuglaunch.json with clientType: Agent
Pattern 2: Data Flow Tracing
Scenario: "Value is wrong after posting"

1. Set breakpoint at final location (where value is wrong)
2. Work backwards to find where value is set
3. Use `usages` tool to find all assignments
4. Set breakpoints at each assignment point
5. Step through to find which execution path is taken
6. Inspect conditions and variable states at each point
Pattern 3: Event Subscriber Not Firing
Scenario: "My event subscriber doesn't execute"

1. Verify subscriber signature exactly matches publisher (name, parameters, types)
2. Check SkipOnMissingLicense and SkipOnMissingPermission attributes
3. Confirm the extension containing the publisher is active and published
4. Set breakpoint inside subscriber body
5. Verify the publisher event is actually being raised (breakpoint in publisher)
6. Check if IsHandled = true is set before your subscriber runs
7. Inspect subscriber execution order (EventPriority)
Pattern 4: Performance Bottleneck
al
// ❌ N+1 pattern — common cause of slow pages
repeat
    Item.Get(SalesLine."No.");      // DB call inside loop
    SalesLine.Amount := Item.Price * SalesLine.Quantity;
until SalesLine.Next() = 0;

// ✅ Use SetLoadFields + single pass
SalesLine.SetLoadFields("No.", Quantity, Amount);
if SalesLine.FindSet() then
    repeat
        // ...
    until SalesLine.Next() = 0;

CPU profile analysis focus:

  • Top time-consuming procedures (hotspots)
  • Frequently called procedures in loops
  • Expensive database operations
  • FlowField CalcFormula complexity
Pattern 5: Snapshot Debugging for Intermittent Issues
⚠️ HUMAN GATE: Snapshots may capture sensitive runtime data.
Before initializing:
1. Confirm what data will be captured
2. Security review for sensitive information
3. Obtain explicit user approval

Commands (one tool — `al_snapshotdebugging` — covers initialize / finish / view):
  al_snapshotdebugging (initialize)   ← start capture session
  [reproduce scenario 10-20 times]
  al_snapshotdebugging (finish)       ← end capture
  al_snapshotdebugging (view)         ← view and compare

Compare snapshots between success and failure cases:
- Variable values at failure point
- Timing differences
- Execution paths taken
- Data state variations

Workflow

Step 1: Context Gathering (MANDATORY before any debugging)

Read existing plans context first:

.github/plans/memory.md              ← project state and recent decisions
.github/plans/*-diagnosis.md         ← previous debug sessions (similar issues)

Gather issue information:

  • What is the expected behavior vs actual behavior?
  • When does it happen: always / sometimes / specific conditions?
  • Exact error message and stack trace
  • Recent code changes (potential regression source)
  • User/permission set and environment where it occurs

Stop criterion: can reproduce the issue consistently (≥80% success rate).

Step 2a: Isolate the Problem (Runtime / Logic)
  1. Narrow down scope with search and usages tools
  2. Identify suspect objects (tables, pages, codeunits, event subscribers)
  3. Attach debugger with selected strategy (Pattern 1)
  4. Set strategic breakpoints:
    • Just before the error occurs
    • At data modification points
    • In event subscribers and validation triggers
  5. Inspect: variable values, record filters, call stack, parameter values
  6. Step execution: F10 (step over), F11 (step into), Shift+F11 (step out)
Step 2b: Configuration Troubleshooting

Authentication failures (401/403, cannot download symbols):

⚠️ HUMAN GATE: Clearing credentials disconnects active sessions.
Confirm impact and obtain approval before clearing the credentials cache
(a VS Code command, not an agent tool).
Then re-authenticate and verify launch.json authentication method.

Missing symbols (unresolved references, red squiggles):

al_downloadsymbols                      ← first attempt
al_downloadsymbols (globalSourcesOnly)  ← if no BC server connection is available
al_build                                ← verify compilation

Check app.json dependencies version alignment.

Build errors — common codes:

  • AL0896 — Recursive FlowField: map dependency graph, break circular chain
  • AL0185 — Object ID conflict: check ID range in app.json, no duplicates
  • AL0118 — Field length mismatch: align extension field length with base table

Publishing failures: check environment connectivity, extension version increment, dependency resolution via al_packages.

Show full SKILL.md (285 more words)Show less
Step 3: Diagnose Root Cause

Identify the exact point of failure and — critically — WHY it occurs:

Common AL root causes by scenario:

SymptomRoot Cause Candidates
Record Not FoundWrong key values, filters blocking read, wrong company context, permission on read
FlowField wrong valueCalcFields not called, incorrect CalcFormula filters, circular dependency (AL0896)
OnValidate not firingDirect assignment without Validate(), IsHandled = true in subscriber, disabled trigger
Custom event not firingSignature mismatch, wrong ObjectType/ObjectId, publisher not raising event, compilation error in subscriber
Slow pageMissing SetLoadFields, N+1 loop, FlowField CalcFormula too complex, missing index/key
Intermittent failureRace condition, timing dependency, data-state dependency, environment-specific
Step 4: Document Diagnosis (MANDATORY)

Create .github/plans/<issue-kebab-case>-diagnosis.md before proposing any fix:

markdown
# Debug Session: <Issue Title>

**Date**: YYYY-MM-DD
**Severity**: Critical / High / Medium / Low
**Status**: Investigating → Diagnosed → Fixed → Verified

## Issue Summary
[Brief description]

## Symptoms
- Expected: [what should happen]
- Actual: [what happens — include exact error text]

## Reproduction Steps
1. [Step]
2. [Step]
**Reproducibility**: Always / Sometimes / Rare

## Root Cause
[Technical explanation with evidence — code snippet, line reference]

## Recommended Fix
[Specific solution. Short-term hotfix + long-term if needed]

## Testing Strategy
- Unit: [what to mock/test]
- Regression: [related functionality to verify]

## Next Steps
1. [Action]
2. [Action]

File naming: sales-posting-error-diagnosis.md, slow-customer-list-diagnosis.md.

Step 5: Propose Fix & Handoff (MANDATORY HITL gate)
  1. Design fix addressing root cause (never symptoms only)
  2. Consider edge cases and side effects
  3. PAUSE — present diagnosis and proposed fix to user for approval
  4. After approval: handoff implementation to al-developer (simple) or via al-conductor TDD cycle (complex refactor)
  5. After fix: run tests, re-profile if performance issue, verify regression scenarios

Clean up: remove debugging artifacts, breakpoints, and temporary logging from code.

References

Constraints

  • This skill covers diagnosis and root cause analysis only — code changes are implemented by al-developer or via al-conductor
  • NEVER guess solutions without evidence from debugging tools
  • NEVER skip Step 4 (diagnosis document) for non-trivial issues (>5 min investigation)
  • NEVER proceed to fix without user approval (Step 5 HITL gate)
  • NEVER leave debugging code, breakpoints, or temporary logging in production code
  • Performance deep-dive (SetLoadFields, FlowField patterns, query optimization) → load skill-performance.md
  • Event publisher/subscriber design patterns → load skill-events.md
  • Permission set generation → load skill-permissions.md

© javiarmesto, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/skill-debug of javiarmesto/ALDC-AL-Development-Collection.

Open the folder on GitHubat commit 161c3e3

Compare with similar skills

Skill Debug next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Skill Debug compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Skill Debug this skilljaviarmesto/ALDC-AL-Development-Collection109—~2.5kAutomated safety check: PassMIT
Trellis Session Insightmindfold-ai/Trellis15k4 repos~1.7kAutomated safety check: PassAGPL-3.0
Native Data FetchingCherryHQ/cherry-studio-app4k6 repos~2.9kAutomated safety check: NotesMIT
Aoti Debugpytorch/pytorch104k1 repos~1.7kAutomated safety check: PassCustom licence
Herdr Throwaway Reproductionherdrdev/herdr43k—~2.4kAutomated safety check: PassApache-2.0
Systematic Debuggingultralisp/ultralisp25851 repos~2.4kAutomated safety check: PassNone

Similar skills

  • Trellis Session Insight

    mindfold-ai/Trellis

    Reach into past AI conversation history through the trellis mem CLI.

    15k GitHub starsUsed in 4 repos~1.7k tokens
    DevelopmentAuto-check passed
  • Native Data Fetching

    CherryHQ/cherry-studio-app

    A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.

    4k GitHub starsUsed in 6 repos~2.9k tokens
    DevelopmentAuto-check: notes
  • Aoti Debug

    pytorch/pytorch

    Debug AOTInductor (AOTI) errors and crashes. An agent skill from pytorch/pytorch.

    104k GitHub starsUsed in 1 repo~1.7k tokens
    DevelopmentAuto-check passed
  • Runs a disposable, uniquely named Herdr session inside an existing one so runtime, pane, terminal or API bugs can be reproduced without touching the main session.

    43k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed
  • Systematic Debugging

    ultralisp/ultralisp

    A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes

    258 GitHub starsUsed in 51 repos~2.4k tokens
    DevelopmentAuto-check passed
  • Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated 4 days ago
    DevelopmentAuto-check: notes

More from javiarmesto/ALDC-AL-Development-Collection

All 14 skills in this repo
  • Skill Agent Instructions

    javiarmesto/ALDC-AL-Development-Collection

    Generate, review, and optimize natural language instructions for Business Central agents (Designer or SDK).

    109 GitHub stars~2.8k tokensUpdated yesterday
    Auto-check passed
  • Skill API

    javiarmesto/ALDC-AL-Development-Collection

    AL API development patterns for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection.

    109 GitHub stars~3.5k tokensUpdated yesterday
    Auto-check passed
  • Skill Copilot

    javiarmesto/ALDC-AL-Development-Collection

    AL Copilot capability development for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection.

    109 GitHub stars~3.5k tokensUpdated yesterday
    Auto-check passed
  • Skill Migrate

    javiarmesto/ALDC-AL-Development-Collection

    AL version migration for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection.

    109 GitHub stars~3k tokensUpdated yesterday
    Auto-check passed
  • Skill Agent Task Patterns

    javiarmesto/ALDC-AL-Development-Collection

    Agent SDK task integration patterns for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection.

    109 GitHub stars~4.2k tokensUpdated yesterday
    Auto-check passed
  • Skill Agent Toolkit

    javiarmesto/ALDC-AL-Development-Collection

    Build, configure, and integrate Business Central agents using the AI Development Toolkit and Agent SDK.

    109 GitHub stars~4.4k tokensUpdated yesterday
    Auto-check passed

Categories

Questions about Skill Debug

What does Skill Debug do?

AL debugging and diagnostics for Business Central. An agent skill from javiarmesto/ALDC-AL-Development-Collection. Skill Debug is an agent skill from javiarmesto/ALDC-AL-Development-Collection. AL debugging and diagnostics for Business Central.

When should I use Skill Debug?

Skill Debug fits situations like: performing snapshot debugging; analyzing telemetry; troubleshooting runtime issues.

How do I install Skill Debug in Claude Code?

Run `npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-debug -a claude-code`. Or copy the skill folder (skills/skill-debug in javiarmesto/ALDC-AL-Development-Collection) into .claude/skills/skill-debug in your project. Claude Code loads it when a task matches its description.

How do I install Skill Debug in Codex?

Run `npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-debug -a codex`. Or copy the skill folder (skills/skill-debug in javiarmesto/ALDC-AL-Development-Collection) into .agents/skills/skill-debug in your project. Codex loads it when a task matches its description.

Can I use Skill Debug in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/skill-debug, .gemini/skills/skill-debug, .github/skills/skill-debug and .opencode/skills/skill-debug in your project.

What does Skill Debug need to run?

SKILL.md names no scripts, command-line tools or credentials: Skill Debug is instructions for the agent only.

Does Skill Debug access the network?

SKILL.md names 1 domain. As links in the text: learn.microsoft.com. This is read from the text; nothing was executed.

Is Skill Debug safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Skill Debug use?

Skill Debug is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Skill Debug use?

About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Skill Debug?

Skills that share tags, products or a category with Skill Debug: Trellis Session Insight (mindfold-ai/Trellis, 15k stars), Native Data Fetching (CherryHQ/cherry-studio-app, 4k stars), Aoti Debug (pytorch/pytorch, 104k stars) and Herdr Throwaway Reproduction (herdrdev/herdr, 43k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Skill Debug?

javiarmesto (a GitHub user) maintains it in javiarmesto/ALDC-AL-Development-Collection, which has 109 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on October 6, 2026.

Source: javiarmesto/ALDC-AL-Development-Collection on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.