Best Practices for Writing Skills and Rules in agents/

This rule applies to any addition or modification to the agents/ directory. When creating new skills or rules, adhere to the following best practices.

1. Rules vs. Skills: When to Use Which

• Use a Rule when you need to enforce high-level constraints, workflow mandates, role restrictions, or high-level directives. Rules are usually "always on" or triggered by specific situations (e.g., debugging). They restrict behavior or mandate specific orchestration.
• Use a Skill when you need to provide a specific technical guide, procedure explanation, or reference implementation for a focused task. Skills provide step-by-step instructions or reference material for a specific domain (e.g., porting a class, using a tool).

2. Structure of a Skill

Every skill must follow this directory structure:

skill-name/
├── SKILL.md              # Required: Metadata + core instructions (<500 lines)
├── scripts/              # Executable code (Python/Bash) designed as tiny CLIs
├── references/           # Supplementary context (schemas, cheatsheets)
└── assets/               # Templates or static files used in output

• SKILL.md: Acts as the "brain." Use it for navigation and high-level procedures.
• References: Link directly from SKILL.md. Keep them one level deep only.
• Scripts: Use for fragile/repetitive operations where variation is a bug. Place long-lived library code in standard repo CLI directories.

3. Frontmatter Optimization

The name and description in the frontmatter of your SKILL.md are the only fields that the agent sees before triggering a skill.

• Strict Naming: The name field must be 1-64 characters, contain only lowercase letters, numbers, and hyphens (no consecutive hyphens), and must exactly match the parent directory name (e.g., name: wiz-testing must live in wiz-testing/SKILL.md). Consider using gerund form (verb + -ing) for Skill names (e.g., processing-pdfs).
• Trigger-Optimized Descriptions: (Max 1,024 characters). Describe the capability in the third person and include specific triggers and "negative triggers". Ensure descriptions do not contain XML tags.
  • Bad: "Wiz skills." (Too vague).
  • Good: "Creates and builds Wiz components using external Sass. Use when the user wants to update component styles or build configurations. Don't use it for external Sass styles with other frameworks."

4. Progressive Disclosure and Resource Management

Maintain a pristine context window by loading information only when needed.

• Keep SKILL.md Lean: Limit the main file to <500 lines. Use it for navigation and primary procedures.
• Use Flat Subdirectories: Move bulky context to standard folders. Keep files exactly one level deep (e.g., references/schema.md, not references/db/v1/schema.md).
• Keep references one level deep from SKILL.md to ensure complete file reads.
• Just-in-Time (JiT) Loading: Explicitly instruct the agent when to read a file (e.g., "See references/auth-flow.md for specific error codes").
• Explicit Pathing: Always use relative paths with forward slashes (/), regardless of the OS. Avoid Windows-style paths.
• For Agents, Not Humans: Omit README.md, CHANGELOG.md, or installation guides. Delete redundant logic.
• Self-Contained: A skill should be entirely self-contained within its directory. Maintain isolation by keeping all files internal to the skill.

5. Writing Instructions for Agents

Create instructions for LLMs instead of humans.

• Tone and Style:
  • Positive Framing: Focus on what the agent should do. If you must specify a constraint, provide an alternative.
    • Bad (Negative): "Do not use Python 2."
    • Good (Positive): "Always use Python 3 for new scripts."
  • Third-Person Imperative: Frame instructions as direct commands (e.g., "Extract the text..." rather than "I will extract...").
• Procedural Instructions:
  • Step-by-Step Numbering: Define workflows as strict chronological sequences.
  • Degrees of Freedom: Match specificity to task fragility. Use low freedom (exact commands) for fragile operations like DB migrations, and high freedom for context-dependent tasks like code reviews.
• Precision and Terminology:
  • Use identical terminology consistently.
  • Use the most specific terminology native to the domain (e.g., "template" instead of "html" in Angular).
• Templates and Examples:
  • Provide concrete templates in assets/ and instruct the agent to copy them.
  • Provide input/output pairs to guide style and detail.
• Intentional Modifications: Only modify a skill when there is a concrete functional reason to do so. Avoid minor rephrasing, cosmetic cleanups, or no-op changes.

6. Deterministic Scripts

Do not write instructions in SKILL.md that require the agent to generate complex parsing logic or boilerplate code from scratch.

• Offload Fragile Tasks: Create tested Python, Bash, or Node scripts in scripts/ for operations like parsing complex datasets or querying databases. Instruct the agent to execute these scripts rather than generating code.
• Graceful Error Handling: Ensure scripts return highly descriptive, human-readable error messages on stdout/stderr so the agent can self-correct based on the output.
• Avoid Voodoo Constants: Document and justify configuration parameters within the scripts or references.

7. Skill Validation and Evaluation

When creating or modifying a skill, you must validate your draft before declaring it complete. If you have the capability to invoke subagents or start new conversations, use the prompts below to automate this validation. If not, perform a self-simulation of these steps.

• Evaluation-Driven Development: Create evaluation scenarios before writing extensive documentation. Define baseline performance expectations.
• Validation Workflow:

  1. Discovery Validation: Invoke a subagent with the following prompt (fill in your frontmatter):

     textCopy

     I am building an Agent Skill based on the spec. Agents will decide whether to load this skill based entirely on the YAML metadata below.
     
     [Paste your YAML frontmatter here]
     
     Based strictly on this description:
     1. Generate 3 realistic user prompts that you are 100% confident should trigger this skill.
     2. Generate 3 user prompts that sound similar but should NOT trigger this skill.
     3. Critique the description: Is it too broad? Suggest an optimized rewrite.
     

  2. Logic Validation: Invoke a subagent with the following prompt (fill in your content):

     textCopy

     Here is the full draft of my SKILL.md and the directory tree of its supporting files.
     
     [Paste your directory structure and SKILL.md here]
     
     Act as an autonomous agent that has just triggered this skill. Simulate your execution step-by-step based on a request to: [Insert a sample request here]
     
     For each step, write out your internal monologue:
     1. What exactly are you doing?
     2. Which specific file/script are you reading or running?
     3. Flag any Execution Blockers: Point out the exact line where you are forced to guess or hallucinate because my instructions are ambiguous.
     

  3. Edge Case Testing: Invoke a subagent with the following prompt:

     textCopy

     Act as a ruthless QA tester. Your goal is to break this skill.
     
     Ask me 3 to 5 highly specific, challenging questions about edge cases, failure states, or missing fallbacks in the SKILL.md. Focus on fragile operations, environment assumptions, and unsupported configurations.
     
     Do not fix these issues yet. Just ask the numbered questions and wait for my answer.
     

8. Checklist for Effective Skills

Before finalizing a skill, verify:

• Description is specific, includes triggers, and is in third person.
• SKILL.md body is under 500 lines.
• File references are one level deep.
• No time-sensitive information.
• Scripts handle errors explicitly and use Unix-style paths.
• Evaluations are created and tested.
• The skill is entirely self-contained and does not reference other skills.
• Modifications are intentional and functional, avoiding cosmetic or no-op changes.