Best Practices for Writing Prompts

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• .claude/settings.json
• .claude/agents/code-reviewer.md
• .claude/skills/testing-patterns/SKILL.md

Introduction

In this project, "prompts" are not just simple questions but are structured as reusable "skills," specialized "agents," and invokable "commands." This system is the core mechanism for integrating the LLM, Claude Code, as a highly effective, context-aware teammate. By defining project conventions, workflows, and domain knowledge in structured markdown files, we enable the model to generate code that adheres to our standards, perform complex tasks like code reviews, and automate maintenance. This document outlines the best practices for creating and managing these prompt constructs.

Sources: README.md:5-8

Core Prompting Constructs

The primary way to instruct Claude is through three types of structured markdown files: Skills, Agents, and Commands. Each serves a distinct purpose in capturing and applying project knowledge.

Skills: Encapsulating Domain Knowledge

Skills are focused markdown documents that teach Claude project-specific patterns, conventions, and best practices. They are the foundation for ensuring generated code matches the existing architecture and style.

• Purpose: To provide specific, reusable knowledge about a single domain, such as testing, UI patterns, or GraphQL schema design.
• Location: .claude/skills/{skill-name}/SKILL.md

Sources: README.md:586-587

A critical part of a skill is its frontmatter, which Claude uses to determine when the skill is relevant.

SKILL.md Frontmatter Fields

Field	Required	Description
name	Yes	Lowercase, hyphenated name matching the directory.
description	Yes	A detailed explanation of what the skill does and when to use it. This is crucial for automatic skill detection.
allowed-tools	No	Comma-separated list of tools Claude can use with this skill (e.g., Read, Grep).
model	No	Specifies a particular model to use for this skill (e.g., claude-sonnet-4-20250514).

Sources: README.md:598-606

Best Practices for Writing Skills:

1. Focused Content: Keep SKILL.md files under 500 lines and focused on a single domain.
2. Trigger-Rich Descriptions: The description field is vital. Use keywords and phrases that a developer would naturally use when discussing the topic, as Claude uses semantic matching to activate skills.
3. Provide Examples: Include both good and bad code examples to clearly illustrate patterns and anti-patterns.
4. Reference Other Skills: Mention related skills to show how different pieces of knowledge connect.
5. Use Exact Filename: The skill file must be named SKILL.md (case-sensitive).

Sources: README.md:622-630

Agents: Specialized Assistants

Agents are AI assistants with a defined purpose, system prompt, and process. They are designed for complex, multi-step workflows.

• Purpose: To act as a specialized assistant for tasks like comprehensive code reviews or managing Git workflows.
• Location: .claude/agents/{agent-name}.md

Sources: README.md:634-637

The agent's prompt defines its persona, process, and any checklists it must follow.

Agent Configuration Fields

Field	Required	Description
name	Yes	Lowercase, hyphenated name for the agent.
description	Yes	A brief explanation of when and why to use the agent.
model	No	The model to use (sonnet, opus, or haiku).
tools	No	A comma-separated list of allowed tools.

Sources: README.md:652-658

An example is the code-reviewer.md agent, which is prompted to follow a detailed checklist covering TypeScript strictness, error handling, and more.

---
name: code-reviewer
description: Reviews code for quality, security, and conventions. Use after writing or modifying code.
model: opus
---

# Agent System Prompt

You are a senior code reviewer...

## Your Process
1. Run `git diff` to see changes
2. Apply review checklist
3. Provide feedback

## Checklist
- [ ] No TypeScript `any`
- [ ] Error handling present
- [ ] Tests included

Sources: README.md:640-650

Commands: Defining Slash Commands

Commands are custom instructions invoked in the chat interface with a / prefix, designed for frequent, well-defined tasks.

• Purpose: To provide quick access to automated workflows, such as reviewing a pull request or generating a PR summary.
• Location: .claude/commands/{command-name}.md

Sources: README.md:662-663

Commands can accept arguments and execute shell commands to gather context.

Command Prompt Format:

• The frontmatter contains a description and a list of allowed-tools.
• The body of the markdown file is the prompt given to Claude.
• $ARGUMENTS captures all arguments passed to the command.
• $1, $2, etc., capture individual positional arguments.
• Inline bash commands like !`git log -5` can be used to inject dynamic information.

Sources: README.md:669-681

An example is the /ticket command, which uses an MCP server to read a JIRA ticket, implement the feature, and update the ticket status.

Sources: README.md:104-106

Automated Prompt Enhancement: The Skill Evaluation System

To avoid manual skill selection, the project uses a powerful skill evaluation system that runs on every prompt submission. This system analyzes the user's prompt and automatically suggests relevant skills.

Sources: README.md:493-495

This process is triggered by the UserPromptSubmit hook defined in .claude/settings.json.

The following diagram illustrates the skill evaluation flow:

This diagram shows how a user prompt is analyzed to automatically suggest skills.

Sources: README.md:497-500, README.md:553-563

Configuration

The logic for this system is defined in skill-rules.json. This file maps skills to a set of triggers, including keywords, regex patterns, and file paths. Each trigger type contributes to a confidence score, and skills that exceed a certain threshold are recommended to the user.

Sources: README.md:501-516, README.md:529-531

An example trigger configuration for a testing-patterns skill:

{
  "testing-patterns": {
    "description": "Jest testing patterns and TDD workflow",
    "priority": 9,
    "triggers": {
      "keywords": ["test", "jest", "spec", "tdd", "mock"],
      "keywordPatterns": ["\\btest(?:s|ing)?\\b", "\\bspec\\b"],
      "pathPatterns": ["**/*.test.ts", "**/*.test.tsx"],
      "intentPatterns": [
        "(?:write|add|create|fix).*(?:test|spec)"
      ]
    }
  }
}

Sources: README.md:532-546

General Best Practices

The README.md and CLAUDE.md files outline several high-level best practices for instructing Claude effectively.

1. Start with CLAUDE.md: This file serves as Claude's persistent memory. It should contain the project stack, key commands, directory structure, and critical rules. This is the foundational context for all interactions.
   Sources: README.md:753-758, CLAUDE.md:1-49
2. Build Skills Incrementally: Do not try to document everything at once. Start with the most common patterns and add new skills as pain points or new conventions emerge.
   Sources: README.md:759-763
3. Activate Skills Explicitly: The CLAUDE.md file instructs the user (and by extension, the model) to check for relevant skills before starting any task. For example, when creating tests, the testing-patterns skill should be activated.
   Sources: CLAUDE.md:41-48
4. Use Hooks for Automation: Automate repetitive tasks like formatting and testing by using PreToolUse and PostToolUse hooks. This reduces the need to explicitly ask Claude to perform these actions.
   Sources: README.md:764-769

Conclusion

Effective prompting in this repository is a systematic process of codifying knowledge. By creating focused Skills, complex Agents, and convenient Commands, we build a library of reusable instructions that ensure consistency and quality. This structured approach, combined with automations like the Skill Evaluation System, transforms the LLM from a general-purpose tool into a specialized, highly integrated development partner that understands and enforces our project's unique conventions.