Repository navigation
Copilot Cli Troubleshooting
This guide helps diagnose and fix common issues when using accessibility agents with GitHub Copilot CLI.
Run these commands in Copilot CLI to diagnose loading issues:
# Check if skills are loaded
/skills list
# Enable debug mode for detailed diagnostics
/troubleshootAccessibility Agents 7.x ships no custom agent files (.agent.md). Every
accessibility agent is an Agent Skill, so /agent listing only the built-in
agents is expected. Look for the skills instead, as below.
-
/skills listshows empty or missing skills - Agent can't access domain knowledge it should have
- "Skill not found" messages
Check where the skills are installed:
The Copilot CLI reads project skills from .github/skills, .claude/skills or
.agents/skills in the repository, and personal skills from
~/.copilot/skills or ~/.agents/skills. npm run setup copies this
package's skills to ~/.agents/skills; the plugin install
(copilot plugin install accessibility-agents@community-access, after
copilot plugin marketplace add Community-Access/accessibility-agents) loads
them from the plugin. A root skills/ folder in a repository is not read.
Each skill is a folder containing SKILL.md:
~/.agents/skills/
accessibility-lead/
SKILL.md
kb-web-scanning/
SKILL.md
Check SKILL.md format:
---
name: accessibility-lead
description: Picks specialists for a web change and merges their findings.
---
# Skill content here...Both name and description are required, and name must match the
folder name.
Only six appear in the model's list: that is by design. Six routers are
model-invocable; the rest set disable-model-invocation: true, and a router
dispatches them.
1. Reload skills:
/skills reload2. Verify skill folder naming:
- Folder names should be lowercase with hyphens
- Must match the
namein SKILL.md
3. Check skill location:
/skills infoThis shows where CLI is looking for skills and which ones are loaded.
Cause: CLI needs approval for certain tools (edit, execute).
Solution: When prompted, choose:
-
1. Yes- approve this use -
2. Yes, and approve for session- approve all uses of this tool in current session
- Accessibility guidance not present in responses
- The edit gate never refuses a UI edit
This package's always-on contract is AGENTS.md; it no longer ships
.github/copilot-instructions.md or *.instructions.md files.
- Check that
AGENTS.mdis present at the repository root you are working in, or that the plugin is installed. - Check the hooks: the plugin wires them through
com.github.copilot/hooks/hooks.json; without the plugin, copyhooks/copilot.hooks.jsonto.github/hooks/in the repository.
Possible causes:
- Large instruction files
- Many skills loaded
- Complex agent prompts
Solutions:
- Use
/compactto compress conversation history - Disable unused skills with
/skills(toggle off) - Check context usage with
/context
/usageThis shows token consumption. High usage may indicate:
- Too many files included in context
- Overly detailed agent instructions
- Skills loading unnecessary content
# List available sessions
/resume
# Continue most recent local session
copilot --continue# Start fresh session
/clear
# Or exit and restart without --continue
copilotFor detailed diagnostics, enable agent debug logging in VS Code settings (these affect CLI too):
{
"github.copilot.chat.agentDebugLog.enabled": true,
"github.copilot.chat.agentDebugLog.fileLogging.enabled": true
}Then in CLI:
/troubleshootThis analyzes debug logs to identify why agents/instructions aren't loading.
Debug sessions can be exported as JSONL for sharing:
- Enable file logging (setting above)
- Run the problematic workflow
- Find logs in
~/.copilot/logs/ - Share the relevant
.jsonlfile for support
PowerShell version: CLI requires PowerShell v6+. Check with:
$PSVersionTable.PSVersionIf using Windows PowerShell 5.1, install PowerShell 7:
winget install Microsoft.PowerShellPath issues:
Ensure ~/.copilot/ resolves correctly. In PowerShell:
$HOME + "\.agents\skills"
# Should show: C:\Users\YourName\.agents\skillsPermissions: Agent files should be readable:
chmod 755 ~/.agents/skills/*/
chmod 644 ~/.agents/skills/*/SKILL.mdIf issues persist:
- Run
/feedbackin CLI to submit a bug report - Check GitHub Copilot CLI documentation
- Open an issue in the accessibility-agents repo
When reporting issues, include:
- CLI version (
copilot --version) - OS and version
- Output of
/skills list - Relevant error messages
- Agents Overview
- Accessibility Lead
- Web Accessibility Wizard
- Document Accessibility Wizard
- Markdown Assistant
- Developer Hub
- GitHub Hub