graybeard

Engineering judgment for Claude Code. Reads before he writes. Asks before he guesses. Ships diffs smaller than the ticket.

Claude Code • Agent Skills • MIT License

---

Graybeard is a universal engineering skill for Claude Code.

It doesn't teach Claude a programming language.

It teaches Claude how experienced software engineers think before changing code.

Instead of generating more code, Graybeard encourages Claude to:

• 📖 Read before editing
• ♻️ Reuse before writing
• 🏗️ Follow the existing architecture
• ✂️ Ship the smallest correct diff
• ✅ Verify with evidence
• 💬 Report assumptions explicitly

Language agnostic.

Framework agnostic.

Repository agnostic.

---

Installation

Graybeard can be installed in three ways depending on your workflow.

Option 1: Claude Code Marketplace (Recommended)

Add the Graybeard marketplace:

/plugin marketplace add Virag-Koradiya/graybeard

Install the plugin:

/plugin install graybeard@graybeard

Note: Run the two commands as separate prompts.

---

Option 2: Install Globally

Makes Graybeard available in every Claude Code project on your machine.

Clone the repository:

git clone https://github.com/Virag-Koradiya/graybeard.git
cd graybeard

macOS / Linux

mkdir -p ~/.claude/skills
cp -r skills/graybeard ~/.claude/skills/

Windows (PowerShell)

if (-not (Test-Path "$HOME\.claude\skills")) {
    New-Item -ItemType Directory "$HOME\.claude\skills" | Out-Null
}

Copy-Item -Recurse .\skills\graybeard "$HOME\.claude\skills\" -Force

---

Option 3: Install for a Single Project

Makes Graybeard available only in the current project.

macOS / Linux

mkdir -p .claude/skills
cp -r /path/to/graybeard/skills/graybeard .claude/skills/

Windows (PowerShell)

if (-not (Test-Path ".\.claude\skills")) {
    New-Item -ItemType Directory ".\.claude\skills" | Out-Null
}

Copy-Item -Recurse "C:\path\to\graybeard\skills\graybeard" ".\.claude\skills\" -Force

Restart Claude Code if it's already running.

Graybeard will automatically activate for coding tasks.

---

Why Graybeard?

Most coding agents fail in predictable ways.

They:

• Assume requirements.
• Write before reading.
• Reinvent code already in the repository.
• Add abstractions that nobody asked for.
• Refactor unrelated files.
• Say "this should work" without proving it.

Graybeard exists to prevent those mistakes before they happen.

Instead of giving coding rules, it provides a decision-making process.

---

The Graybeard Loop

Every change follows the same workflow.

Understand
    ↓
Decide
    ↓
Build
    ↓
Verify
    ↓
Report

Every step removes a common AI failure mode.

Step	Prevents
Understand	Hallucinated APIs, misunderstood code
Decide	Wrong assumptions, unnecessary dependencies
Build	Over-engineering, speculative abstractions
Verify	"Should work" without evidence
Report	Hidden assumptions and unclear tradeoffs

---

Example

Without Graybeard

Add a DELETE endpoint.

The agent:

• creates new validation logic
• invents a response format
• refactors unrelated files
• adds a helper that already exists

Result:

Large diff.

Repository becomes less consistent.

---

With Graybeard

The agent:

• reads neighboring endpoints
• reuses existing validation
• matches repository conventions
• changes only the required lines
• reports one assumption

Result:

Small diff.

Looks like a human wrote it.

---

Principles

Graybeard isn't another list of best practices.

It encodes engineering judgment.

Examples include:

• Read before editing.
• Ask only when ambiguity matters.
• Prefer existing code over new code.
• Match the repository before applying "best practices."
• Keep changes proportional to the task.
• Verify instead of assuming.
• Report assumptions explicitly.

When principles conflict, Graybeard follows this order:

1. Correctness & Security
2. Repository Consistency
3. Simplicity
4. DRY
5. Personal Preference

---

How Graybeard fits into the ecosystem

Ponytail asks:

"Can we write less code?"

Graybeard asks:

"What's the safest, smallest, most maintainable change?"

The two complement each other well.

---

Who is this for?

Graybeard is a good fit if you:

• use Claude Code daily
• work across multiple repositories
• review AI-generated code
• care about maintainability
• prefer small, focused pull requests

---

Design Goals

Graybeard optimizes for:

• Correctness
• Small diffs
• Codebase consistency
• Maintainability
• Low token usage
• Minimal explanations

It intentionally avoids:

• Language-specific advice
• Framework-specific rules
• Team workflows
• Git conventions
• Infrastructure guidance

Those belong in your project's CLAUDE.md.

---

Inspiration

Graybeard builds on ideas from several excellent projects:

• Ponytail for its pragmatic approach to minimal, maintainable code.
• Andrej Karpathy Skills for lightweight behavioral guidelines that improve coding agents.
• Anthropic Agent Skills for the official skill format, examples, and ecosystem. :contentReference[oaicite:0]{index=0}
• Claude Code Skill Documentation for skill authoring concepts and best practices. :contentReference[oaicite:1]{index=1}

Graybeard extends these ideas into a universal engineering judgment layer focused on understanding, decision-making, implementation, verification, and reporting.

---

Philosophy

Graybeard isn't a collection of coding rules.

It's a decision-making framework.

Every change follows the same process:

Understand before editing.

Decide before building.

Build only what's needed.

Verify with evidence.

Report only what's useful.

License

MIT. Boring, owned, and it works.