Agentic Principles

A practical framework and installable AI skill for evaluating whether an experience is genuinely agent-led—and whether the human oversight inside it is meaningful.

The central diagnostic has two edges:

1. Who is doing the work? Is the human operating the workflow while AI assists, or is the agent doing the work while the human steers?
2. Is the approval real? Can the human make an informed judgment, or has approval become a rubber stamp?

What this project provides

• Agentic Critique skill for Claude Code and Codex
• Three analysis modes: critique an existing flow, re-storyboard it before/after, or design a new agent-led flow
• A 15-principle framework covering agency, guidance, oversight, trust, consent, autonomy, advocacy, and failure
• 13 named anti-patterns including the chat-bar bolt-on, rubber-stamp, undo fantasy, and moral crumple zone
• Figma critique cards when compatible Figma read and write tools are available
• Self-contained HTML reports for durable, shareable critique output
• Three evaluation scenarios covering assist-in-disguise, unsafe approval, and non-fintech re-storyboarding

The skill evaluates the agentic interaction layer. It does not replace usability, accessibility, visual-design, security, legal, or compliance review.

Install for Claude Code

Claude Code is the primary supported environment.

git clone https://github.com/thecsiz/agentic-principles.git
cd agentic-principles
mkdir -p ~/.claude/skills/agentic-critique
cp -R skills/agentic-critique/. ~/.claude/skills/agentic-critique/

Claude Code discovers personal skills from ~/.claude/skills/<skill-name>/SKILL.md. Start Claude Code in the project containing the flow you want to review, then invoke:

/agentic-critique Critique this agent flow: [describe the flow]

Claude may also load the skill automatically when a request matches its description.

Useful Claude prompts

/agentic-critique Is this actually agentic, or is the human still doing the work?

/agentic-critique Show me the agent-led before/after version of this onboarding flow.

/agentic-critique Help me design a new agentic approval flow for [task].

Add critique cards to Figma

Be explicit when you want writeback:

/agentic-critique Critique this flow and add the critique cards to the Figma file: [Figma URL]

What happens:

1. The skill reads the linked frames and reconstructs the flow.
2. It runs both edges of the diagnostic and scores P0–P15.
3. It creates a diagnostic card, per-step actor cards, and the most consequential findings.
4. It verifies that the cards were actually written and reports their location.

Figma reading and writing are separate capabilities. Reading requires a configured Figma integration. Writing requires a tool that can execute Figma Plugin API code in the open file. If write access is missing, the skill must say so and return the critique in chat; it must never claim cards were added when they were not.

If you share a Figma URL without specifying an output, the skill asks whether you want cards added or a chat-only critique.

Create an HTML report

Ask for a report when you want a durable local artifact:

/agentic-critique Critique this flow and create a self-contained HTML report.

The skill authors structured report data and runs:

node skills/agentic-critique/scripts/build-report.js report.json --out agentic-critique.html

The report is created locally. Publishing it requires a separate, explicit request.

Use with Codex

Install the same skill folder into Codex:

git clone https://github.com/thecsiz/agentic-principles.git
cd agentic-principles
mkdir -p ~/.codex/skills/agentic-critique
cp -R skills/agentic-critique/. ~/.codex/skills/agentic-critique/

Then invoke it with:

$agentic-critique Critique this agent flow: [describe the flow]

The bundled agents/openai.yaml supplies Codex-facing display metadata. The critique workflow and reference material are shared with Claude Code.

How the knowledge base works

The skill's knowledge base is deliberately small and inspectable:

• references/principles.md contains P1–P15 and the two-edged P0 diagnostic.
• references/rubric.md turns the framework into a complete scorecard.
• references/anti-patterns.md contains the named failure modes.
• references/worked-example.md demonstrates the before/after output shape.

Every critique reads the principles, walks the observed flow step by step, scores the rubric, checks the anti-patterns, and cites the best-supported principle or anti-pattern for each finding. It must not invent principle numbers.

The longer principles-shareable.md is the human-readable framework. principles-for-agentic-design-medium.md is an essay-length introduction.

Repository map

.
├── principles-shareable.md
├── principles-for-agentic-design-medium.md
├── skills/agentic-critique.skill
└── skills/agentic-critique/
    ├── SKILL.md
    ├── agents/openai.yaml
    ├── evals/evals.json
    ├── LICENSE
    ├── references/
    └── scripts/

Validate the project

node _tools/validate.js

The validator checks the skill structure, all P0–P15 rubric rows, the 13 anti-patterns, renderer syntax and vocabulary, the HTML fixture, the packaged archive, licensing files, private references, and common secret patterns.

Status and limitations

This is a working framework, not finished doctrine. Its sharpest claims—especially whether a flow can collapse work into a few decisions while preserving genuine judgment—should be pressure-tested across domains and stakes.

The framework was shaped by high-stakes consumer and financial-product work, but the public material is product-agnostic. Treat domain-specific legal and compliance requirements as separate review layers.

License

This repository uses two licenses:

• Skill behavior, evaluation plumbing, and scripts: MIT
• Principles, anti-patterns, examples, articles, and explanatory documentation: CC BY 4.0

See LICENSE for the exact scope map and THIRD_PARTY_NOTICES.md for notices.