New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Zcode Configuration Guide

by zai-org in zai-org/ZCode

A skill your agent uses when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client.

Apache-2.0Auto-check passedAgent Workflows

Install Zcode Configuration Guide

skills CLI
$ npx skills add zai-org/ZCode --skill zcode-configuration-guide -a claude-code

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

GitHub CLI
$ gh skill install zai-org/ZCode zcode-configuration-guide --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/zai-org/ZCode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/apps/zcode-cli/packages/zcode-guide-plugin/skills/zcode-configuration-guide .claude/skills/zcode-configuration-guide && 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
zcode-configuration-guide
GitHub stars
7.7k
Token cost
~2.5k tokens
SKILL.md length
1,191 words
Files
1
Skills in repo
5
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client.

  • Works in 6 steps: Explicitly configured roots → User ~/.zcode/skills (or commands) → User ~/.agents/skills → …
  • Configuring ZCodes extension resources (MCP servers
  • SKILL.md covers How things are configured, Scopes and the main…, The five resources at a glance and Instructions / AGENTS.md:…, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Zcode Configuration Guide is an agent skill from zai-org/ZCode. Use when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Explains where each resource is configured at the user and workspace scope, the discovery order, precedence, and merge rules, plus guidance on which location to choose. Use when someone asks how to add an MCP server, command, skill, hook, plugin, or AGENTS.md instructions, where a configuration file lives, why a configuration is not taking effect…

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 Agent Workflows, covering Hooks and plugins, MCP servers and Agent instruction files. It works with Model Context Protocol. The repository describes itself as: Z.ai's coding agent harness. Powerful, intelligent, extensible. The licence is Apache-2.0.

When your agent uses it

  • Configuring ZCodes extension resources (MCP servers
  • Instruction files such as AGENTS.md in the ZCode client
  • Someone asks how to add an MCP server
  • AGENTS.md instructions

Example prompts

  • “/zcode-configuration-guide”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Explicitly configured roots
  2. User ~/.zcode/skills (or commands)
  3. User ~/.agents/skills
  4. Workspace .zcode/skills (from the current directory up to the repository root; every level counts)
  5. Workspace .agents/skills
  6. Enabled plugin roots (lowest precedence)

What it can do on your machine

Read from SKILL.md and the folder at commit aac4755. 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.

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

  • Network

    No URLs in SKILL.md.

    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

Zcode Configuration Guide loads about 2.5k tokens when it runs. Until then it costs about 148 tokens; SKILL.md has 1,191 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~148
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 zai-org/ZCode at commit aac4755, republished under its Apache-2.0 licence (© zai-org). 1,191 words, ~2,528 tokens.

Download SKILL.mdSave it as .claude/skills/zcode-configuration-guide/SKILL.md (or your agent's skills folder).
name
zcode-configuration-guide
description
Use when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Explains where each resource is configured at the user and workspace scope, the discovery order, precedence, and merge rules, plus guidance on which location to choose. Use when someone asks how to add an MCP server, command, skill, hook, plugin, or AGENTS.md instructions, where a configuration file lives, why a configuration is not taking effect, or needs routing to a specific diagnostic skill.

ZCode Configuration Guide

ZCode supports five types of extension resources, plus AGENTS.md instruction files. This skill is the map: it tells you where each resource is configured and how conflicts are resolved. For "something is not working, how do I fix it," follow the routing to the diagnosing-* skills at the end.

How things are configured

There are two ways to work with configuration in the ZCode client, and this plugin serves both:

  • A person manages resources through the client's graphical interface — Settings → Plugin Management, Settings → Skills, Settings → Subagents, Settings → MCP, and the / menu in the input box.
  • An agent repairs configuration by reading and editing the underlying files directly with its file tools. The locations and rules below are what an agent uses to find the right file and field.

Scopes and the main configuration files

  • User scope — lives under your home directory and applies to every workspace.
  • Workspace scope — lives inside a repository and applies only to that project; can be shared with a team through version control.
  • User configuration file: ~/.zcode/cli/config.json. Holds MCP servers, hooks, plugin enable/disable state, and skill/command disable overrides.
  • Workspace configuration file: <repo>/.zcode/config.json (or <repo>/zcode.json).
  • User instruction file: ~/.zcode/AGENTS.md. Applies as default instructions for every workspace.
  • Workspace instruction file: <repo>/AGENTS.md. Applies only to that project; the current workspace path is searched upward until the project root.

The five resources at a glance

ResourceFormUser scopeWorkspace scopeConflict rule
SkillsDirectory + SKILL.md~/.zcode/skills/, ~/.agents/skills/<repo>/.zcode/skills/, <repo>/.agents/skills/Identity is the file path; on load the first same-named skill wins (user scope has priority)
Commands.md file~/.zcode/commands/, ~/.agents/commands/<repo>/.zcode/commands/, <repo>/.agents/commands/Deduplicated by normalized command name; first match wins (user scope overrides workspace), the loser is ignored
MCPJSON object~/.zcode/cli/config.json → mcp.servers (fallback ~/.agents/mcp.json → mcpServers)<repo>/.zcode/config.json → mcp.servers (fallback <repo>/.agents/mcp.json → mcpServers)User overrides workspace for a same-named server; workspace-scoped servers are trusted and auto-connected by default, same as user-scoped
Hookshooks.json / config object~/.zcode/cli/config.json → hooks<repo>/.zcode/config.json → hooksConfiguration-file hooks require hooks.enabled: true; plugin hooks are appended
PluginsDirectory + plugin.jsonInstalled from a marketplace; enable/disable state stored in ~/.zcode/cli/config.json—A plugin contributes skills, commands, hooks, MCP servers, and agents
InstructionsAGENTS.md file~/.zcode/AGENTS.md<repo>/AGENTS.mdUser default instructions load first, then workspace instructions load later so the workspace can narrow or override broad defaults

Note: .agents/mcp.json is a compatibility fallback for MCP. Within each scope the client reads .zcode first; only if that scope has no MCP servers does it fall back to .agents/mcp.json (which uses a top-level mcpServers key, whereas .zcode uses nested mcp.servers).

Instructions / AGENTS.md: merge order

AGENTS.md is not a skill, command, hook, MCP server, or plugin. It is the instruction file ZCode loads into the model context for broad behavior rules.

  • User scope: ~/.zcode/AGENTS.md. Use this for personal defaults that should apply in every workspace, such as preferred language, review style, or local workflow conventions.
  • Workspace scope: <repo>/AGENTS.md. Use this for repository-specific rules that should be shared with the project, such as architecture boundaries, logging rules, testing requirements, and commit/MR policy.
  • Resolution: ZCode searches for the workspace AGENTS.md from the current working directory upward until the detected project root. The user default file is resolved from the user's home directory.
  • Merge order: when both files exist, ZCode injects ~/.zcode/AGENTS.md first, then the resolved workspace AGENTS.md. Workspace instructions appear later, so they can narrow or override broad user defaults for that repository.
  • Migration and creation: onboarding can copy existing user memory from ~/.claude/CLAUDE.md into ~/.zcode/AGENTS.md. The built-in /init command targets the current workspace AGENTS.md, creating or updating repository instructions instead of editing the user default file.

Skills and commands: discovery order (identical)

Locations are scanned in this order (earlier locations take precedence):

  1. Explicitly configured roots
  2. User ~/.zcode/skills (or commands)
  3. User ~/.agents/skills
  4. Workspace .zcode/skills (from the current directory up to the repository root; every level counts)
  5. Workspace .agents/skills
  6. Enabled plugin roots (lowest precedence)

Within a level, .zcode is scanned before .agents. A deeper working-directory location takes precedence over a repository-root location.

  • Skills merge: identity is the file path, so same-named skills at different paths are all discovered, but only the first in discovery order is loaded — higher-precedence copies shadow the rest.
  • Commands merge: the key is the normalized command name, and the first match wins; duplicates are ignored. Nested directories join into the name with a colon: review/code.md becomes /review:code (not /review/code).
Show full SKILL.md (469 more words)Show less

MCP: merge and auto-connect

  • Override order for a same-named server: CLI override → environment → user → workspace → system defaults. In short, user overrides workspace. Plugin-provided servers form the base layer and are overridden by explicit configuration.
  • Auto-connect: MCP servers from every scope — user, workspace, plugin, environment, and CLI — are trusted and connected automatically at session start. (Workspace-scoped servers were previously untrusted and required manual authorization; they now connect by default like any other scope.) Use Settings → MCP to inspect status and repair server configuration.

Hooks: essentials

  • Supported events (exactly seven): SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop.
  • Configuration-file hooks must set hooks.enabled: true to run (disabled by default). When any plugin contributes a hook, the hook runner is enabled automatically.

Plugins: essentials

  • Managed in Settings → Plugin Management (the Installed and Discover tabs). A plugin directory carries a manifest at .zcode-plugin/plugin.json (the compatibility names .claude-plugin/ and .codex-plugin/ are also recognized). The minimal manifest requires only name (matching ^[a-z0-9][a-z0-9._-]{0,127}$).
  • Component fields: commands, skills, hooks, mcpServers, agents (each may be a directory name, an array, or inline). The fields channels, lspServers, outputStyles, and settings are recorded but not executed.
  • Enable/disable state is stored under plugins in ~/.zcode/cli/config.json. A built-in plugin can be disabled but not uninstalled.
  • Marketplaces can be added (via the + button on the Discover tab) from a GitHub repository, a Git URL, a local directory, or a file.

Choosing where to configure

  • Personal, used across projects → user scope (~/.zcode/... or ~/.agents/...).
  • Team- or project-shared, versioned with the repository → workspace scope (<repo>/.zcode/... or .agents/...).
  • Shared with other coding agents that read ~/.agents/skills/ → put skills there; to override a same-named skill only inside ZCode, use .zcode/skills/.
  • Personal default instructions → ~/.zcode/AGENTS.md; repository-specific instructions → <repo>/AGENTS.md. If both exist, keep broad preferences in the user file and project rules in the workspace file.
  • MCP servers → user configuration for personal servers, or workspace configuration to share with a team; both scopes connect automatically. Because opening a project now auto-connects the MCP servers declared in its configuration, only open workspaces you trust.
  • Secrets → never commit them to version control; use environment variables or local settings.

When something is wrong — route to a diagnostic skill

When a configuration is read but has no effect, or reports an error, load the matching skill. Each provides a symptom → cause → check → fix workflow, covering both what to click in the client and which file and field an agent should edit:

  • MCP server not connecting, tools missing, untrusted, or timing out → diagnosing-mcp
  • A skill is not discovered, not triggering, shadowed, or disabled → diagnosing-skills
  • A /command is missing, overridden, has a frontmatter error, or arguments do not substitute → diagnosing-commands
  • A hook does not trigger, its matcher does not match, its script is not executable, or it blocks unexpectedly → diagnosing-hooks
  • A plugin is not listed, fails to install, has missing components, or is not enabled → diagnosing-plugins

© zai-org, Apache-2.0. 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 apps/zcode-cli/packages/zcode-guide-plugin/skills/zcode-configuration-guide of zai-org/ZCode.

Open the folder on GitHubat commit aac4755

Compare with similar skills

Zcode Configuration Guide 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.

Zcode Configuration Guide compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Zcode Configuration Guide this skillzai-org/ZCode7.7k—~2.5kAutomated safety check: PassApache-2.0
Agent Setup Health Audittw93/Waza7.2k—~5.2kAutomated safety check: NotesMIT
Working With Claude Code Docsobra/superpowers-developing-for-claude-code142—~1.5kAutomated safety check: PassNone
Claude Code Mastery Squadohmyjahh/xquads-squads277—~1.1kAutomated safety check: PassMIT
Mistral Vibe CLI Referencemistralai/mistral-vibe5.1k—~15kAutomated safety check: NotesApache-2.0
Claude Codekid-sid/claude-spellbook190—~3.9kAutomated safety check: PassMIT

Similar skills

  • Agent Setup Health Audit

    tw93/Waza

    Audits a project's agent configuration, instruction drift, hooks, MCP and AI maintainability, then reports prioritized findings with evidence and next actions.

    7.2k GitHub stars~5.2k tokensUpdated today
    Agent WorkflowsAuto-check: notes

  • Working With Claude Code Docs

    obra/superpowers-developing-for-claude-code

    Looks up official Claude Code documentation stored as reference files instead of guessing about CLI commands, configuration, or plugin APIs.

    142 GitHub stars~1.5k tokensUpdated 10 mo ago
    Agent WorkflowsAuto-check passed

  • Claude Code Mastery Squad

    ohmyjahh/xquads-squads

    Routes a request to one of eight specialist agents covering hooks, skills, subagents, MCP integration and context engineering for Claude Code.

    277 GitHub stars~1.1k tokensUpdated 11 days ago
    Agent WorkflowsAuto-check passed

  • Mistral Vibe CLI Reference

    mistralai/mistral-vibe

    Official

    Reference for Mistral Vibe, the CLI agent it runs inside: config files, env vars, agents, skills, tools, hooks and MCP servers, so the agent can explain and troubleshoot its own setup.

    5.1k GitHub stars~15k tokensUpdated yesterday
    Agent WorkflowsAuto-check: notes

  • Claude Code

    kid-sid/claude-spellbook

    A skill your agent uses when configuring Claude Code — installing skills or agents, writing hook configurations, setting up tool permissions, registering MCP servers, or authoring CLAUDE.md project…

    190 GitHub stars~3.9k tokensUpdated 2 mo ago
    Agent WorkflowsAuto-check passed

  • MCP Integration for Plugins

    anthropics/claude-plugins-official

    Official

    Explains how to bundle Model Context Protocol servers in a Claude Code plugin, covering config files, stdio, SSE, HTTP and WebSocket server types, and authentication.

    38k GitHub starsUsed in 11 repos~3.1k tokens
    Agent WorkflowsAuto-check passed

More from zai-org/ZCode

All 25 skills in this repo

  • DOCX

    zai-org/ZCode

    Complete DOCX document creation, editing, and analysis capabilities with support for revisions, comments, formatting preservation, and text extraction.

    7.7k GitHub stars~4.9k tokensUpdated yesterday
    Auto-check: notes

  • Visualize

    zai-org/ZCode

    Create visualizations and interactive tools directly in conversation.

    7.7k GitHub stars~8.7k tokensUpdated yesterday
    Auto-check passed

  • PDF

    zai-org/ZCode

    Professional PDF toolkit covering four production workflows: reports, creative visuals, academic LaTeX, and existing PDF processing.

    7.7k GitHub stars~18k tokensUpdated yesterday
    Auto-check: notes

  • Restore Legacy Sessions

    zai-org/ZCode

    A skill your agent uses when ZCode needs to inspect, plan, or execute restoration of old ACP-era ZCode sessions from ~/.zcode/v2/sessions into the new ZCode task/session stores.

    7.7k GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed

  • Zcode Large Task Fixture

    zai-org/ZCode

    Generate, verify, or remove large synthetic ZCode task fixtures in local ~/.zcode persistence for UI/session performance testing.

    7.7k GitHub stars~698 tokensUpdated yesterday
    Auto-check passed

  • Architecture Governance

    zai-org/ZCode

    Check ZCode module and layer boundaries for code changes. An agent skill from zai-org/ZCode.

    7.7k GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Zcode Configuration Guide

What does Zcode Configuration Guide do?

A skill your agent uses when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Zcode Configuration Guide is an agent skill from zai-org/ZCode.md in the ZCode client.

When should I use Zcode Configuration Guide?

Zcode Configuration Guide fits situations like: configuring ZCodes extension resources (MCP servers; instruction files such as AGENTS.md in the ZCode client; someone asks how to add an MCP server; AGENTS.md instructions.

How do I install Zcode Configuration Guide in Claude Code?

Run `npx skills add zai-org/ZCode --skill zcode-configuration-guide -a claude-code`. Or copy the skill folder (apps/zcode-cli/packages/zcode-guide-plugin/skills/zcode-configuration-guide in zai-org/ZCode) into .claude/skills/zcode-configuration-guide in your project. Claude Code loads it when a task matches its description.

How do I install Zcode Configuration Guide in Codex?

Run `npx skills add zai-org/ZCode --skill zcode-configuration-guide -a codex`. Or copy the skill folder (apps/zcode-cli/packages/zcode-guide-plugin/skills/zcode-configuration-guide in zai-org/ZCode) into .agents/skills/zcode-configuration-guide in your project. Codex loads it when a task matches its description.

Can I use Zcode Configuration Guide 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 zai-org/ZCode --skill zcode-configuration-guide -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/zcode-configuration-guide, .gemini/skills/zcode-configuration-guide, .github/skills/zcode-configuration-guide and .opencode/skills/zcode-configuration-guide in your project.

What does Zcode Configuration Guide need to run?

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

Does Zcode Configuration Guide access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Zcode Configuration Guide 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 Zcode Configuration Guide use?

Zcode Configuration Guide is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Zcode Configuration Guide use?

About 2.5k tokens (SKILL.md is roughly 10k 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 Zcode Configuration Guide?

Skills that share tags, products or a category with Zcode Configuration Guide: Agent Setup Health Audit (tw93/Waza, 7.2k stars), Working With Claude Code Docs (obra/superpowers-developing-for-claude-code, 142 stars), Claude Code Mastery Squad (ohmyjahh/xquads-squads, 277 stars) and Mistral Vibe CLI Reference (mistralai/mistral-vibe, 5.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Zcode Configuration Guide?

zai-org (a GitHub organization) maintains it in zai-org/ZCode, which has 7,659 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on October 10, 2026.

Source: zai-org/ZCode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.