claude-code-philosophy

Claude Code Philosophy

Design better agents.

claude-code-philosophy is a public skill and plugin package for developers who want to build agentic systems that are actually useful: controllable, legible, recoverable, and grounded in real product constraints.

It is inspired by the design philosophy behind Claude Code-class agent systems, but written as vendor-neutral guidance that can help builders working with Codex, Claude Code, or their own custom agent runtimes.

This project is unofficial. It is not affiliated with Anthropic.

Why this exists

A lot of agent projects are still too shallow:

• great demo, weak product
• many tools, no capability model
• “memory” with no boundaries
• autonomy with no control surface
• impressive output, fragile runtime

This project exists to push in the other direction.

The core belief is simple: the difference between a toy agent and a useful one is usually the harness, not just the model or the prompt.

What you get

This repository currently ships one installable skill:

• agent-design-coach

It helps developers:

• turn fuzzy agent ideas into concrete system designs
• review an existing agent for harness, tool, memory, safety, and UX gaps
• decide whether a workflow needs a real agent or a simpler tool
• make vibe-coded AI projects more disciplined and useful

What the skill teaches

The skill is built around a few strong principles:

• harness-first design
• explicit tool and permission boundaries
• layered memory instead of one giant blob
• recovery and durability as first-class features
• human control as part of the product
• practical usefulness over fake autonomy

Quick install

Codex: install the skill directly

Inside Codex, run:

$skill-installer install https://github.com/dadwadw233/claude-code-philosophy/tree/main/skills/agent-design-coach

Then restart Codex.

Claude Code: install through the repository marketplace

Inside Claude Code, run:

/plugin marketplace add dadwadw233/claude-code-philosophy
/plugin install claude-code-philosophy@claude-code-philosophy

Then invoke the installed skill with:

/claude-code-philosophy:agent-design-coach

Manual install

• Codex: copy this repo to ~/.codex/plugins/claude-code-philosophy and register it in ~/.agents/plugins/marketplace.json
• Claude Code: copy skills/agent-design-coach to ~/.claude/skills/agent-design-coach

Detailed examples are below.

Installation details

Codex: direct skill install

This is the simplest path if you only want the skill itself.

$skill-installer install https://github.com/dadwadw233/claude-code-philosophy/tree/main/skills/agent-design-coach

After installation, restart Codex.

Codex: local plugin install

Clone the repo:

git clone [email protected]:dadwadw233/claude-code-philosophy.git

Copy it into your local plugin area:

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/claude-code-philosophy ~/.codex/plugins/claude-code-philosophy

Create or update ~/.agents/plugins/marketplace.json:

{
  "name": "personal-plugins",
  "interface": {
    "displayName": "Personal Plugins"
  },
  "plugins": [
    {
      "name": "claude-code-philosophy",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/claude-code-philosophy"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Restart Codex. The plugin should appear in the plugin directory.

Claude Code: marketplace install

This repository includes a Claude Code marketplace manifest at .claude-plugin/marketplace.json.

Register the marketplace:

/plugin marketplace add dadwadw233/claude-code-philosophy

Install the plugin:

/plugin install claude-code-philosophy@claude-code-philosophy

After installation, the explicit slash command is:

/claude-code-philosophy:agent-design-coach

Claude Code: manual skill install

Copy the skill directory:

mkdir -p ~/.claude/skills
cp -R skills/agent-design-coach ~/.claude/skills/agent-design-coach

For a manually installed standalone skill, invoke:

/agent-design-coach

How to use it

Codex

• Use $agent-design-coach to turn this coding-agent idea into a real system architecture.
• Use $agent-design-coach to review this repo's agent design for harness, memory, permissions, and UX gaps.

Claude Code plugin install

• /claude-code-philosophy:agent-design-coach
• /claude-code-philosophy:agent-design-coach Review this coding agent and tell me what is weak in its harness design.

Claude Code standalone skill install