Skip to main content
skill CX Codex

expert-instruction — Claude Code skill: features and installation

The expert-instruction Claude Code skill helps design system instructions for AI agents. It covers agent roles, behavioral limits, response formats, and tool-use guidance.

MIT 106 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill expert-instruction -a claude-code
Open on GitHub

What expert-instruction does

The skill helps shape persistent instructions that govern an agent across conversations. It covers identity and capabilities, behavioral boundaries, response structure, tool selection, and handoffs to a human. Multi-step workflows and guardrails are part of the material too.

It calls out common prompt problems, including conflicting rules, vague personas, and missing tool-error handling. Its guidance recommends keeping system prompts below 2000 tokens and moving extra detail into reference documents. It also covers adversarial testing and tracking prompt versions.

This is for an agent’s lasting behavior, not tuning a single query or configuring training. The README points to the prompt skill for general techniques such as few-shot prompting and structured output.

What it helps with

  • define an agent’s role and domain boundaries
  • set tool selection rules and fallback behavior
  • specify a consistent response structure
  • decide when the agent should hand work to a human
  • find conflicting rules in a system prompt

Example prompts for the agent

  • Write a system prompt for a support agent with a clear role, limits, and response format.
  • Set rules for when the agent should call tools and how it should respond to tool errors.
  • Review this system prompt for conflicting instructions and out-of-scope requests.

How to install expert-instruction

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill expert-instruction -a claude-code

2Manually: put the files in place

~/.claude/skills/expert-instruction/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/expert-instruction/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about expert-instruction

How do I install expert-instruction in Claude Code?

Run npx skills add oakoss/agent-skills --skill expert-instruction -a claude-code. The skill file is at ~/.claude/skills/expert-instruction/SKILL.md.

What does expert-instruction do?

It helps create persistent system instructions for AI agents, covering identity, constraints, output structure, tool use, and behavior across multiple turns.

How is expert-instruction different from the prompt skill?

expert-instruction focuses on an agent’s ongoing behavior and boundaries. The README directs general prompt techniques, including few-shot and structured output, to the prompt skill.

Source text

SKILL.md · MIT
---
name: expert-instruction
description: |
  System prompt design and instruction crafting for AI agents. Covers persona definition, constraint specification, output formatting, tool use instructions, multi-turn behavior, and guardrail design.

  Use when writing system prompts for AI products, designing agent personas, specifying behavioral constraints, crafting tool-use instructions, or building multi-step agent workflows.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
user-invocable: false
---

# Expert Instruction Design

## Overview

Expert instruction design focuses on crafting system prompts that define how an AI agent behaves, what it can and cannot do, and how it responds across interactions. Unlike general prompt engineering (which optimizes individual queries), this skill covers the **persistent behavioral layer** that shapes an agent's identity, capabilities, and constraints.

**When to use:** Writing system prompts for AI products, defining agent personas for customer-facing tools, specifying behavioral guardrails, crafting tool-use guidance, or designing multi-step agent workflows.

**When NOT to use:** One-off prompt optimization (use the `prompt` skill), fine-tuning or training-time configuration, infrastructure-level safety (use model provider safety features), or tasks that do not involve LLM agent behavior.

## Quick Reference

| Pattern                  | Purpose                                  | Key Points                                       |
| ------------------------ | ---------------------------------------- | ------------------------------------------------ |
| Identity block           | Define who the agent is                  | Role, expertise, communication style             |
| Capability declaration   | State what the agent can do              | Explicit tool list, domain boundaries            |
| Constraint specification | Define behavioral boundaries             | Hard limits, soft preferences, escalation rules  |
| Output format rules      | Ensure consistent response structure     | Templates, progressive disclosure, length limits |
| Tool use instructions    | Guide when and how to use tools          | Selection criteria, error handling, sequencing   |
| Multi-turn behavior      | Handle conversation continuity           | Context tracking, topic switching, memory        |
| Guardrails               | Prevent harmful or out-of-scope behavior | Content boundaries, instruction hierarchy        |
| Escalation triggers      | Define when to hand off to humans        | Confidence thresholds, scope boundaries          |

## Common Mistakes

| Mistake                                  | Correct Pattern                                               |
| ---------------------------------------- | ------------------------------------------------------------- |
| System prompt over 4000 tokens           | Keep under 2000 tokens, move details to reference docs        |
| Contradictory instructions               | Audit for conflicts, establish priority order                 |
| Vague persona ("be helpful")             | Specific: expertise domain, response style, knowledge bounds  |
| No escalation path                       | Define when agent should defer to human or say "I don't know" |
| Listing every edge case                  | State principles, provide examples for ambiguous cases only   |
| Mixing identity and task instructions    | Separate: identity block first, task instructions second      |
| No output format specification           | Define structure: headings, lists, code blocks, length        |
| Tool instructions without error handling | Include fallback behavior when tools fail or return errors    |
| Testing only happy-path inputs           | Test adversarial, off-topic, and edge case inputs             |
| Deploying without versioning             | Track system prompt versions, log changes, enable rollback    |

## Delegation

- **Prompt technique exploration**: Use `Explore` agent to research patterns
- **System prompt testing**: Use `Task` agent to run adversarial test suites
- **Code review**: Delegate to `code-reviewer` agent for integration code

> If the `prompt` skill is available, delegate general prompt engineering techniques (CoT, few-shot, structured output) to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s prompt -a claude-code -y`

## References

- [System prompt design: anatomy, personas, tools, and multi-turn behavior](references/system-prompt-design.md)
- [Guardrails and testing: behavioral boundaries, versioning, and production readiness](references/guardrails-and-testing.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

SKILL.md skills catalog →
gjkim-instruction gjkim42 The gjkim-instruction skill keeps a root brief for long-running agent loops, separating required outcomes and approved choices from unresolved implementation details. CX Codex +1 4,600installs 10_instruction_stress centminmod 10_instruction_stress is a Claude Code prompt that tests whether a model follows four simultaneous constraints while describing an imaginary coffee shop. GP ChatGPT ★ 2,744repo stars find-skills vercel-labs find-skills is a Claude Code skill that locates agent skills for a task and helps assess the results. It activates when someone asks for a capability that may already be installable. CX Codex +1 4,400,000installs frontend-design official anthropics The frontend-design skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. CX Codex +1 1,025,790installs agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs design-taste-frontend Leonxlnx The design-taste-frontend Claude Code skill sets design rules and checks for websites. It activates for new pages, redesigns, and requests to fix a generic-looking site. CX Codex +1 802,600installs grill-me Matt Pocock grill-me interviews you about a plan or design to expose gaps and sharpen decisions. Use it before implementation starts. CX Codex +1 1,424,476installs grill-with-docs Matt Pocock The grill-with-docs skill interviews you about a plan or design and creates ADRs and a glossary along the way. Use it when decisions need sharper definition. CX Codex +1 1,219,756installs

From the same set106

The whole set →
turborepo This Claude Code skill helps configure Turborepo in JavaScript and TypeScript monorepos. Use it to set up task pipelines, caching, package filters, and CI workflows. CX Codex +1 108installs realtime-sync realtime-sync guides agents through designing low-latency sync using WebTransport, CRDT conflict resolution, and batched AI token streaming. CX Codex +1 108installs plan-first-development The plan-first-development Claude Code skill structures project planning and tracks progress across sessions. It activates for new projects, major features, and work split into phases. CX Codex +1 107installs tracer-bullets The tracer-bullets Claude Code skill splits multi-layer work into end-to-end slices. Each slice is checked before work moves on. CX Codex +1 107installs codebase-packager The codebase-packager Claude Code skill prepares large repositories for AI coding tasks. It builds digests, packs source context, and traces connections across files. CX Codex +1 105installs skill-management skill-management — a Claude Code skill for creating, reviewing, and validating skills against the Agent Skills standard. It comes into play during structure checks, description edits, and manifest comparisons. CX Codex +1 105installs meta-agent-creator The meta-agent-creator Claude Code skill helps define custom subagents and configure their settings. Use it to shape task delegation and control which tools an agent can access. CX Codex +1 104installs localization-engineer localization-engineer is a Claude Code skill that guides internationalization and localization architecture. It structures ICU messages, CLDR plurals, RTL layouts, and multilingual SEO. CX Codex +1 103installs

Project sponsors

Companies that keep this analytics open