The /skills command is the first thing to run when a skill isn't behaving. It shows exactly what Claude loaded at startup and how it parsed each description. Everything downstream in skill debugging starts from what this command shows you.

TL;DR: Running /skills in Claude Code lists every skill loaded in the current session, with the name and description as Claude parsed them. If a skill doesn't appear, it wasn't loaded. Comparing the /skills output to your actual SKILL.md files is the fastest way to diagnose loading failures, truncation, and frontmatter errors in AEM's skill framework.

What does the /skills command show?

/skills outputs a list of all skills loaded in the current session, showing two fields for each skill: the name and the description, exactly as Claude parsed them from the SKILL.md frontmatter at startup. What you see is the system prompt representation, not the raw file. For each skill, it shows:

  • Name: The value from the name field in the SKILL.md frontmatter
  • Description: The value from the description field in the SKILL.md frontmatter, as Claude parsed it

The list reflects the state at session startup. Skills added after the session started do not appear. The command is read-only — it shows what loaded, it does not reload or refresh anything.

One important nuance: the output shows the description as Claude received it in the system prompt, which means any formatting artifacts introduced by YAML parsers or text processors will appear here. If your description has a line break in the YAML, the /skills output shows the truncated first line only. Anthropic's skill authoring docs note that Claude uses these descriptions to select from potentially 100+ available skills, which means a garbled description isn't a minor cosmetic issue (Anthropic Agent Skills documentation, platform.claude.com, 2025).

How do I read the /skills output for debugging?

Reading the /skills output is a three-step cross-check: presence, accuracy, and completeness. Each check targets a different failure mode. Together they cover the three ways a skill can silently break at load time: missing entirely, loaded with a corrupted description, or loaded but outnumbered by the skills you expected.

  1. Is your skill in the list at all? If it's missing, the skill didn't load. The file path is wrong, the file is misnamed, the frontmatter is invalid, or the session started before the skill was created. See Why Does Claude Say 'No Skills Found' When I Run /skills for the full file-loading diagnostic.

  2. Does the description match what you wrote? Open your SKILL.md and compare the description: value to what /skills shows. If the output is shorter, the description was truncated. The truncation point tells you which trigger phrases are invisible to the classifier.

  3. Are all the skills you expect present? Count the skills in the output vs the skill folders in .claude/skills/. If the count is lower than expected, some skills didn't load. The difference is where to look for errors.

"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." — Boris Cherny, TypeScript compiler team, Anthropic (2024)

The /skills command is that spec, revealed. What you see there is precisely what Claude is working from.

What does it mean if a description looks shorter than expected?

A shorter-than-expected description in /skills output points to one of three causes: YAML parsing cut the text at a line break, the per-field 1,024-character ceiling was hit, or the total system prompt budget for all descriptions was exhausted. Each cause produces a different truncation pattern and has a different fix.

  • Multi-line description in YAML. If your SKILL.md has a description: that spans more than one line, Claude parses only the first line. The rest is treated as a YAML continuation block, not part of the description value. Fix: put the description on a single line and quote it if it contains special characters.

  • 1,024-character limit hit. The description field has a hard 1,024-character maximum (Anthropic Agent Skills best practices, platform.claude.com). Text beyond that position is cut. Count your description characters. If you're at or above 1,024, rewrite to compress. In Claude Code specifically, the /skills listing displays only the first 250 characters of each description, regardless of the stored length, a behavior documented in GitHub issue #40121 on the Claude Code repo (Anthropic, github.com/anthropics/claude-code, 2025).

  • System prompt budget exceeded. When total skill descriptions across all loaded skills exceed the skill listing budget, later descriptions get truncated at the system prompt level. In Claude Code, this budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters (Anthropic Claude Code documentation, code.claude.com). This is separate from the per-description 1,024-character limit. The /skills output shows the actual truncated text that made it into the system prompt. Count all visible description characters in the /skills output. If the total approaches the budget, you're hitting the ceiling.

For a detailed analysis of budget issues and multi-skill interference, see What Causes Multiple Skills to Interfere With Each Other.

How do I verify a specific skill loaded correctly?

The fastest verification method is to ask Claude directly after running /skills: quote the description back to you. This works because Claude reads the system prompt representation, not the file, so any discrepancy between what Claude reports and what you wrote in SKILL.md is the exact gap causing activation failures.

What is the description for my [skill-name] skill?

Claude will quote the description from the loaded system prompt. Compare that to your SKILL.md file. Any difference between what Claude reports and what you wrote is the source of the activation problem.

A more thorough verification: ask Claude to list every constraint, trigger condition, and output format from a specific skill. If Claude lists things you didn't write, or misses things you did write, there's a content discrepancy between your file and what Claude parsed. Anthropic's skill authoring docs flag first-person descriptions (e.g., "I can help you process Excel files") as a known discovery failure mode. Claude needs third-person phrasing to correctly inject the description into the system prompt (Anthropic Agent Skills best practices, platform.claude.com).

In our commission workflow, we run this verification check as standard preflight before declaring a skill production-ready. Skills that pass self-testing but fail this verification step have a YAML parsing issue that's invisible without explicitly querying the loaded content (AEM production protocol, 2025).

What does it mean when /skills shows nothing at all?

"No skills found" means Claude did not find or could not parse any SKILL.md files at session startup. The three root causes are a wrong launch directory, missing skill subfolders, or total frontmatter parse failure. All three are diagnosable in under two minutes with directory checks alone.

  1. Claude Code was launched from a directory that doesn't contain .claude/skills/
  2. The .claude/skills/ directory exists but contains no valid subfolders with SKILL.md files
  3. All skills have frontmatter errors that caused complete parse failure

Check which directory Claude Code was launched from. If you're on a project that has .claude/skills/, but you launched Claude Code from a parent directory, the skills in the project subdirectory are invisible. Launch from the project root.

The broader pattern this fits: 66% of developers in the 2025 Stack Overflow Developer Survey named "AI solutions that are almost right, but not quite" as their top frustration (Stack Overflow Developer Survey, 2025). A skill that loads but fails silently is the configuration-layer version of that problem.

See How Do I Check If Claude Can See My Skill Files for the full diagnostic when /skills returns nothing.

What can't /skills tell me?

/skills shows the loading result only: names and parsed descriptions. It cannot tell you why a skill activated or failed to activate, what the SKILL.md body contains, or whether reference files are accessible. Loading and activation are two separate systems, and /skills only surfaces the first one.

  • Why a skill isn't triggering. Loading and activation are separate. A skill that appears in /skills with a correct description can still fail to activate if the description's trigger phrases don't match how users phrase requests. Jesse Vincent's analysis of Claude Code skill loading (blog.fsck.com, 2025) confirmed that the two failure modes, not loading and not triggering, are diagnostically distinct and require separate tools.
  • Whether the skill body (SKILL.md content below the frontmatter) loaded correctly. The command only shows frontmatter fields. SKILL.md body content issues only surface when the skill is actually invoked.
  • Reference file content. Reference files load on demand, not at startup. /skills has no information about whether reference files exist or are readable.

For activation problems in skills that show up correctly in /skills, start with the activation troubleshooting guide at How Do I Troubleshoot Skill Description Activation Issues Systematically.

FAQ

Q: The /skills output shows my skill name but not the description. What happened? The description field is missing from your SKILL.md frontmatter, or the frontmatter failed to parse. Open SKILL.md and check that the description: key exists between the --- markers and has a non-empty value. If the YAML is syntactically broken (missing closing ---, for example), no fields will appear in the output.

Q: I have 15 skills installed but /skills only shows 12. Which ones are missing? Compare the skill names in the /skills output to the folder names in .claude/skills/. The folders with no match in the output are the ones that failed to load. Check each missing skill's SKILL.md for frontmatter errors.

Q: Can I use /skills to check if a skill I just installed is ready to use? Only if you restart the session after installing it. The /skills output reflects what was present at session startup. A skill installed mid-session will not appear until you start a fresh session.

Q: The /skills output shows my description correctly, but the skill still doesn't activate automatically. What now? Correct display in /skills confirms loading, not activation. The description content is right, but the trigger phrases may not match how prompts are phrased in practice. Move to activation testing: build a 10-prompt test set and run it in a fresh session to identify the gap between your description's trigger vocabulary and actual prompt vocabulary.

Q: Is there a way to see the full SKILL.md body content, not just the description? Not via /skills. Ask Claude to describe the skill's process steps, rules, or output format after invoking it. Claude will reference the loaded skill body in its response, which tells you whether the full content was parsed correctly. Alternatively, ask directly: "What steps does my [skill-name] skill follow?"

Last updated: 2026-04-21