L5: Custom Slash Commands and Skills

Custom Slash Commands and Skills

In the previous lesson, we used CLAUDE.md to define passive rules—instructions Claude Code reads before acting. However, true architectural efficiency comes from creating active workflows. This lesson covers how to extend the Claude Code REPL (Read-Eval-Print Loop) by building Custom Slash Commands and defining custom Skills, transforming a general AI assistant into a highly specialized tool for your specific codebase.

1. The Limitation of Native Commands

Out of the box, Claude Code comes with native slash commands like /compact (to manage context), /clear (to wipe the session), and /help.

While useful, these are generic. In an enterprise environment, developers perform highly specific, repetitive tasks: running a specialized test suite, scaffolding a new microservice according to internal boilerplate, or triggering a custom deployment script. Forcing developers to type out the full prompt for these complex tasks every time is inefficient and prone to error.

2. Custom Slash Commands (Workflow Aliases)

A Custom Slash Command is essentially an alias or a macro. It maps a simple terminal command (e.g., /scaffold-api) to a massive, predefined prompt or workflow.

Architectural Value:

Standardization: If your team has a strict 15-step checklist for reviewing a Pull Request, you do not want developers manually asking Claude to do it. You define a /pr-review command. When triggered, Claude executes the exact, standardized 15-step prompt designed by the architecture team.
Token Efficiency: Instead of a developer typing a paragraph of context, the slash command automatically injects the exact right context needed for the task, preventing token waste.

3. Skills (Custom Agentic Tools)

While a Slash Command is a shortcut for a prompt, a Skill is a new tool added to Claude Code's internal toolbelt.

By default, Claude Code knows how to use standard tools like git, grep, and npm. But what if your company uses a proprietary internal CLI (e.g., acme-deploy) or heavily relies on kubectl for infrastructure?

Defining a Skill: You teach Claude Code a new Skill by defining it in your configuration. You must provide the command name, a description of what it does, and the expected inputs.
Agentic Execution: Once a Skill is defined, Claude Code can use it autonomously. If a user asks, "Check the status of the staging pods," Claude Code will realize it needs the kubectl Skill, format the correct shell command, and execute it.

4. Implementation via Configuration

In the Claude Code ecosystem, custom commands and skills are typically defined within your project's configuration (often an extension of CLAUDE.md or a dedicated JSON/YAML config file in the project root).

Example Conceptual Implementation:

YAML

# claude-config.yaml
commands:
  - name: "/lint-fix"
    description: "Runs the corporate linter and automatically fixes all styling errors in the current working directory."
    prompt: "Run `npm run lint:fix`. If any errors remain, read the error output, explain why they occurred, and edit the files to resolve them strictly following the corporate style guide."

skills:
  - name: "terraform-apply"
    description: "Deploys infrastructure changes to the specified environment."
    allowed_commands: ["terraform plan", "terraform apply"]

5. The `allowed-tools` Restriction (Security)

When you give Claude Code custom skills—especially those that interact with infrastructure or run build scripts—you introduce severe security risks. A hallucination could result in Claude accidentally running terraform destroy instead of terraform plan.

Architectural Enforcement:

To prevent this, architects use the allowed-tools or allowed-commands paradigm.

You do not give Claude Code raw shell access to do whatever it wants.
If you create a Skill for managing Docker, you strictly whitelist the exact commands it is allowed to run (e.g., docker build, docker logs).
If Claude Code attempts to run a command outside of that whitelist (e.g., docker rm -f), the local client physically blocks the execution, returns an error to the model, and forces it to escalate to the human user for manual override.

6. Session Forking (`context:fork`)

When building complex Slash Commands, architects often utilize a pattern called Forking.

If a developer is 40 turns deep into a debugging session, and they suddenly run /run-heavy-tests, injecting the massive test output into the current context window will degrade the agent's memory of the debugging session.

The Fork Pattern: You configure the Slash Command to execute in a forked context (context:fork). The agent temporarily spawns a parallel session, runs the heavy tests, synthesizes the results into a concise summary (e.g., "3 tests failed in auth.py"), and then returns only that summary to the main debugging session. This keeps the primary context window clean and focused.