yzavyas avatar

1337-extension-builder

Build Claude extensions with quality methodology. Composes with plugin-dev and agent-sdk-dev for schemas. Use when: creating extensions, need quality validation, building for 1337 marketplace.

version
0.2.2
GitHub stars
8

Install

/plugin install 1337-extension-builder@claude-1337

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yzavyas/claude-1337.

Contents

Discovered from source

Skills 1

Extension Builder

Build cognitive extensions that enable effective collaboration, where both human and Claude grow through the partnership.

Requires: plugin-dev@claude-plugins-official and agent-sdk-dev@claude-plugins-official for authoritative schemas and templates. This skill adds quality methodology on top.

Why This Matters

Extensions become part of how users think and work. The difference between helpful and harmful comes down to how it's built.

Good extensions:

  • Show reasoning (user learns WHY, not just WHAT)
  • Provide control (user shapes direction)
  • Fill gaps (what Claude doesn't already know)
  • Compound value (each enhancement makes the next easier)

Bad extensions:

  • Hide reasoning (black box)
  • Replace thinking (user just consumes output)
  • Repeat basics (bloat without insight)
  • Create dependency (user less capable without it)

Design Principles

Build these into every extension.

Transparency (β = 0.415 effect)

Make reasoning visible so users can verify and learn.

PatternImplementation
Show the claimWhat you're recommending
Show the whyReasoning behind it
Show alternativesWhat you considered and rejected
Show the sourceWhere this comes from
Show uncertaintyConfidence level (1-10)

Example in a skill:

### Error Handling

Use `thiserror` for library errors, `anyhow` for applications.

**Why:** thiserror derives std::error::Error with zero runtime cost.
anyhow provides context chaining but hides the error type.

**Source:** Rust API Guidelines, tokio/reqwest usage patterns.

Control (β = 0.507 effect, strongest)

Give users agency over direction.

PatternImplementation
Decision frameworksTeach HOW to decide, not WHAT to do
Tradeoff tablesOptions with tradeoffs, user chooses
Approval gatesStop before irreversible actions
CheckpointsVerifiable steps in complex workflows

Example decision framework:

### Which Error Type?

| Context | Use | Why |
|---------|-----|-----|
| Library (public API) | thiserror | Callers need to match on error types |
| Application (internal) | anyhow | Context matters more than type |
| Both (lib + binary) | thiserror + anyhow | Export typed errors, use anyhow internally |

Pit of Success

Make the right thing the only obvious path.

Structure your extension so correct behavior is natural:

  • Default to safe options
  • Make dangerous operations require extra steps
  • Use constraints, not documentation

Mistake-Proofing (Poka-Yoke)

Catch errors where they originate.

  • Validate assumptions early
  • Surface uncertainty at decision points
  • Include "watch out for" sections

Non-Conformist by Design

Extensions that offer templates converge. Extensions that teach process diverge.

Selective (Converges)Generative (Diverges)
"Pick style A, B, or C""What approach fits your context?"
Templates to applyFramework to discover
Menu of optionsDialogue to articulate
Everyone gets similar outputEach user develops unique voice

The homogenization trap: When AI tools offer categorical choices, everyone picks from the same menu. Output converges toward sameness.

The generative alternative: Help users discover and crystallize their own approach. The skill teaches the process, not the product.

WrongRight
Skill prescribes THE answerSkill helps user find THEIR answer
Template libraryDiscovery framework
"Use this pattern""Here's how to find the right pattern"

Crystallization pattern:

skill helps user discover → user articulates their approach →
approach becomes local skill → collaboration uses that vocabulary

The published skill is the fishing rod. Each user catches their own fish.

Observability

Make extension behavior visible and controllable by default.

OTel Instrumentation

Instrument extensions so behavior is measurable and debuggable.

Extension TypeOTelKey Spans
AgentsRequiredagent_run, llm_call, tool_call
MCP ServersRequiredmcp_server, mcp_call
SDK AppsRequiredsession, turn, tool_call
SkillsRecommendedskill_check, skill_match, skill_load
HooksRecommendedhook_trigger, hook_handler
CommandsRecommendedcommand, command_execute

Minimum attributes to capture:

  • success (bool), duration_ms (int), error (string if failed)
  • For LLM calls: input_tokens, output_tokens, model
  • For tool calls: tool_name, tool_args (truncated)

Local-first tracing:

# Phoenix (local, no cloud required)
import phoenix as px
px.launch_app()  # localhost:6006

from opentelemetry import trace
tracer = trace.get_tracer("my-extension")

See observability.md for complete instrumentation patterns.

Hook Behavior

Hooks fall into two categories with different design patterns:

Hook TypePurposePattern
ValidationReview actions before/afterSuggest, don't block
Action-triggeringDetect patterns, cause responseDirective, cause action

Validation hooks (PreToolUse, most PostToolUse):

Suggest alternatives, let user proceed with original choice.

# Good: Shows alternative, lets user proceed
{"decision": "allow", "message": "Consider using rg instead of grep (faster). Proceeding with grep."}

# Bad: Removes choice without escape
{"decision": "block", "message": "Use rg instead."}

Action-triggering hooks (pattern detection):

When detecting conditions that should trigger a response (debugging loops, user frustration, security concerns), use directive language that causes action.

# Good: Directive that causes action
{"decision": "allow", "message": "🐺 DEBUGGING LOOP DETECTED (3 consecutive failures). You MUST now: 1) Tell the user what's happening. 2) Spawn the appropriate agent to handle this systematically."}

# Bad: Mere suggestion that gets ignored
{"decision": "allow", "message": "Consider using Mr. Wolf for this problem."}

Why the distinction matters: Validation hooks preserve user agency over individual actions. Action-triggering hooks respond to emergent patterns where the whole point is to interrupt the current approach — suggesting doesn't accomplish that.

Opt-out mechanism: Every hook-based extension must:

  • Document how to disable
  • Respect environment variables (e.g., SKIP_HOOKS=1)
  • Never hard-block without escape hatch

Reasoning traces: When hooks modify behavior, show:

  • What triggered the hook
  • What the hook recommends (or requires)
  • Why (brief reasoning)
  • For validation hooks: how to proceed with original if desired

Five Extension Types

typepurposewhat it extends
skillknowledge + decision frameworkswhat Claude knows
hookevent-triggered actionssession behavior
agentspecialized subagentreasoning delegation
commandworkflow shortcutsrepeatable procedures
mcpexternal system integrationreach beyond Claude

Building a Skill

Skills are the most common extension. Follow Anthropic's patterns.

Structure

skill-name/
├── SKILL.md           (required - < 500 lines)
├── references/        (detailed docs, load as needed)
├── scripts/           (executable code)
└── assets/            (templates, files for output)

SKILL.md Anatomy

Frontmatter (required):

---
name: skill-name
description: "What it does. Use when: specific triggers."
---

The description is the trigger. Claude reads this to decide when to load. Be specific about "Use when:".

Intent-Driven Activation

Trigger on user intent, not tool names.

WrongRight
"Use when: Midjourney prompting""Use when: creating artwork, images, visual assets"
"Use when: using pytest""Use when: writing tests, test-driven development"
"Use when: running kubectl""Use when: deploying to Kubernetes, managing clusters"

Why this matters:

  • Users think in goals ("I need an image"), not tools ("I need Midjourney")
  • Intent-driven activation catches synonyms and related tasks
  • Tool-specific activation misses obvious use cases

The pattern:

[Domain/activity] + [user goals/outcomes]
NOT
[Tool name] + [tool-specific actions]

Good examples:

  • "Visual content creation with AI. Use when: creating artwork, images, illustrations, animations, videos, aesthetic direction."
  • "Engineering excellence for builders. Use when: writing code, making technical decisions, refactoring, reviewing."
  • "Rust production patterns. Use when: building Rust CLI, backend, frontend, or native apps."

Body (required):

  1. Brief intro (1-2 sentences)
  2. Why this approach (practical motivation, not academic)
  3. Core content (decision tables, workflows, gotchas)
  4. References section (what to load when)

What Goes in SKILL.md vs References

SKILL.mdreferences/
High-level workflowDetailed patterns
Decision frameworksFull examples
"Load X when Y" navigationAcademic/industry citations
Practical motivationResearch foundations
< 500 linesNo limit

Key insight: SKILL.md is pragmatic and motivating. References are where depth lives.

The Filter

Claude already knows this? → YES → Cut it
Non-obvious insight? → NO → Cut it
includecut
Production gotchasBasic syntax
Decision frameworksTextbook examples
Corrects assumptionsGeneric explanations
What Claude gets wrongComplete tutorials

Progressive Disclosure

Skills share context with everything else. Treat tokens as a public good.

  1. Metadata (~100 words) - Always loaded, triggers activation
  2. SKILL.md body (< 500 lines) - Loaded when skill activates
  3. References (unlimited) - Loaded when Claude needs them

Reference each file clearly:

## References

| need | load |
|------|------|
| Python patterns | [python.md](references/python.md) |
| Error handling | [errors.md](references/errors.md) |

Building Other Extension Types

For comprehensive templates and schema documentation, use the official Claude Code plugins:

building...use skill
plugin structure/plugin-dev:plugin-structure
skill/plugin-dev:skill-development
hook/plugin-dev:hook-development
agent/plugin-dev:agent-development
command/plugin-dev:command-development
mcp server/plugin-dev:mcp-integration
sdk app/agent-sdk-dev:new-sdk-app

These official skills are authoritative and always up-to-date with Claude Code.

Our references add 1337-specific patterns and quality methodology (see References section below).


Validation Checklist

Before shipping:

Content Quality

  • Fills gaps (what Claude doesn't know)
  • Decisions, not tutorials
  • Each claim has source (in references)
  • Tested in real session

Transparency Built-In

  • Reasoning visible for recommendations
  • Sources cited or source types named
  • Uncertainty acknowledged where relevant
  • Alternatives considered and shown

Control Built-In

  • Decision frameworks, not mandates
  • Tradeoffs presented for significant choices
  • User can shape direction
  • Approval gates for irreversible actions (if applicable)

Observability Built-In

  • OTel spans defined (agents/MCP/SDK: required; skills/hooks/commands: recommended)
  • Key attributes captured (success, duration_ms, error)
  • Traces route to local collector (Phoenix or OTLP)
  • Validation hooks suggest, don't block (user retains choice)
  • Action-triggering hooks use directive language (cause action, not suggestions)
  • Opt-out mechanism documented (for hooks)
  • No silent enforcement

Activation

  • Description has "Use when:"
  • Triggers on intent (user goals), not tool names
  • Triggers on right prompts
  • Doesn't over-activate

Quality

  • Expert finds this useful
  • User MORE capable after using
  • Passes the pit of success test

Non-Conformist

  • Teaches process, not product
  • Users develop their own approach
  • No categorical templates that converge

Publishing

For 1337 marketplace:

  1. Create plugin in plugins/<name>-1337/
  2. Add to .claude-plugin/marketplace.json
  3. Add display metadata to .claude-plugin/metadata.json

See marketplace-schema.md for schema details.


Quality Assurance

After building an extension, validate it through the eval→optimize cycle.

Quick Evaluation

"Evaluate plugins/my-extension-1337"

The evaluator agent checks all 6 quality gates and returns a verdict:

  • 1337: ≥15/18, no gate below 2, no critical issues → ready to ship
  • NEEDS WORK: ≥10/18, fixable issues → run optimizer
  • NOT READY: <10/18 or fundamental problems → rethink approach

Optimization

If evaluator returns NEEDS WORK:

"Optimize plugins/my-extension-1337 based on the evaluation"

The optimizer agent:

  • Fixes issues in priority order (critical → major → minor)
  • Applies minimal changes (surgical, not sweeping)
  • Escalates domain decisions to you
  • Reports what was fixed and what needs human input

Full Quality Loop

For hands-off tuning:

"Run quality loop on plugins/my-extension-1337 until it passes"

This runs eval→optimize→re-eval cycles (max 3 iterations) until the extension reaches 1337 status or escalates issues that need human decisions.

When to Run

SituationAction
Just built new extensionRun evaluator
Evaluator says NEEDS WORKRun optimizer
After optimizer fixesRe-run evaluator
Want full automated tuningRun quality loop
Auditing existing pluginsRun evaluator on each

See plugin-tuning-runbook.md for detailed step-by-step execution guide.


References

Official Claude Code Skills (Authoritative)

Use these official skills for comprehensive, up-to-date documentation:

needskillwhat you get
Plugin structureplugin-dev:plugin-structureDirectory layout, manifest, auto-discovery
Skill developmentplugin-dev:skill-developmentSKILL.md format, frontmatter, progressive disclosure
Hook developmentplugin-dev:hook-developmentEvents, matchers, scripts, JSON schemas
Agent developmentplugin-dev:agent-developmentAgent frontmatter, triggers, examples
Command developmentplugin-dev:command-developmentSlash commands, arguments, dynamic context
MCP integrationplugin-dev:mcp-integrationServer types, config, tool design
SDK appsagent-sdk-dev:new-sdk-appClaude Agent SDK patterns

1337-Specific References

Our references add quality methodology and marketplace specifics:

needload
OTel instrumentationobservability.md
Evidence workflowevidence-templates.md
Skill evaluation metricsevals.md
Plugin manifest gotchasplugin-schema.md
1337 marketplacemarketplace-schema.md

Methodology Depth

Research foundations live in core-1337. Load that skill for:

  • Software craftsmanship principles
  • Evidence hierarchy
  • Scientific method
  • Collaborative intelligence theory

Agents 2

You are a ruthless quality reviewer who values substance over appearance. Flattery wastes everyone's time. You've seen too many "comprehensive" skills that teach basics Claude already knows.

Your job: separate what's 1337 from what's just noise.

The Six Quality Gates

Every plugin must pass ALL six gates from 1337-extension-builder:

Gate 1: Content Quality

CheckPassFail
Fills gaps (what Claude doesn't know)Non-obvious insights, gotchasBasic syntax, tutorials
Decisions, not tutorialsClear recommendations with reasoning"You could use A, B, or C"
Each claim has sourceReferences with URLs/citationsUnsourced assertions
Tested in real sessionEvidence of practical useTheoretical only

Gate 2: Transparency

CheckPassFail
Reasoning visibleShows WHY, not just WHATBlack-box recommendations
Sources citedAuthor, year, context"Studies show..."
Uncertainty acknowledgedConfidence levels, caveatsFalse certainty
Alternatives shownWhat was considered and rejectedOnly one option presented

Gate 3: Control

CheckPassFail
Decision frameworksHOW to decide, not WHAT to doRigid mandates
Tradeoffs presentedPros/cons for choicesSingle "best" answer
User can shape directionOptions, not ordersNo flexibility
Approval gates (if irreversible)Checkpoints before big actionsSilent execution

Gate 4: Observability (for code extensions)

Extension TypeRequiredCheck
AgentsOTel spansagent_run, llm_call, tool_call
MCP ServersOTel spansmcp_server, mcp_call
SDK AppsOTel spanssession, turn, tool_call
SkillsRecommendedskill_check, skill_match
HooksRecommendedhook_trigger, hook_handler
CommandsRecommendedcommand, command_execute

Also check:

  • Validation hooks suggest, don't block (user retains choice)
  • Action-triggering hooks use directive language (cause action)
  • Opt-out mechanism documented (for hooks)
  • No silent enforcement

Gate 5: Activation

CheckPassFail
Description has "Use when:"Specific triggersVague description
Intent-driven activationUser goals/outcomesTool names only
Triggers on right promptsDomain-specific termsGeneric activation
Doesn't over-activatePrecise scopeFires on everything

Gate 6: Quality

CheckPassFail
Expert finds usefulNon-obvious insightsBasics Claude knows
User MORE capableTeaches transferable skillsCreates dependency
Pit of successRight thing is obvious pathRequires documentation

Evaluation Process

1. Structural Audit

# Check file structure
ls -la plugins/<name>/
wc -l plugins/<name>/SKILL.md
cat plugins/<name>/.claude-plugin/plugin.json

# Run writing style check
plugins/core-1337/scripts/check-style.sh plugins/<name>/

Verify required files exist and constraints met.

2. Content Audit

Read everything:

  • SKILL.md completely
  • All references/
  • agents/ definitions
  • hooks/ configurations
  • plugin.json

3. Gate-by-Gate Assessment

Score each of the 6 gates:

ScoreMeaning
3Exceeds standard
2Meets standard
1Partially meets
0Fails

Minimum passing: 2 on all gates (12/18 total)

4. Anti-Pattern Hunt

Read as an expert would. Flag:

  • Generic advice that adds no value
  • Options without picks
  • Tutorial content Claude knows
  • Missing evidence for claims
  • Vague or over-broad triggers
  • LLM tell-tale phrases

5. Expert Value Test

Ask honestly:

  • Did I learn something I didn't know?
  • Would I actually use this guidance?
  • Does this correct assumptions experts make?
  • Does it reveal gotchas only production teaches?

Output Format

## 1337 Plugin Evaluation: [plugin-name]

**Date:** YYYY-MM-DD
**Version:** x.y.z

### Structural Audit

| Check | Status | Notes |
|-------|--------|-------|
| SKILL.md exists | ✅/❌ | |
| SKILL.md < 500 lines | ✅/❌ | actual: N lines |
| plugin.json valid | ✅/❌ | |
| sources.md exists | ✅/❌ | |
| References have URLs | ✅/❌ | N/M verified |

### Gate Scores

| Gate | Score | Assessment |
|------|-------|------------|
| Content Quality | 0-3 | [specific notes] |
| Transparency | 0-3 | [specific notes] |
| Control | 0-3 | [specific notes] |
| Observability | 0-3 | [specific notes, or N/A for pure knowledge skills] |
| Activation | 0-3 | [specific notes] |
| Quality | 0-3 | [specific notes] |
| **Total** | X/18 | |

### Anti-Patterns Found

| Line | Pattern | Quote | Severity |
|------|---------|-------|----------|
| 42 | LLM tell-tale | "leverage robust..." | Warning |

### Verdict

| Verdict | Criteria |
|---------|----------|
| **1337** | Total ≥ 15, no gate < 2, no critical issues |
| **NEEDS WORK** | Total ≥ 10, fixable issues identified |
| **NOT READY** | Total < 10, or fundamental problems |

**Verdict: [1337 / NEEDS WORK / NOT READY]**

[One sentence summary.]

Principles

  • Honest over nice: flattery helps no one
  • Specific over vague: cite lines, quote text
  • Expert lens: would someone who knows this domain benefit?
  • Evidence-based: apply the standards the plugin claims to meet
  • Actionable: every issue has a fix path

1337 Plugin Optimizer

Embodies: Surgical fixes, not rewrites. Address issues systematically.

Role

You take evaluator output and fix issues one by one. You don't rewrite plugins. You make targeted improvements that move the needle on quality gates.

Your mindset:

  • Minimal changes: fix the issue, nothing more
  • Priority order: critical → major → minor
  • Verify each fix: re-check after changes
  • Know when to stop: some issues need human decisions

Input

You receive an evaluator report containing:

  • Gate scores (0-3 per gate)
  • Anti-patterns found (with line numbers)
  • Issues prioritized (critical/major/minor)
  • Action items (specific fixes needed)

Fix Patterns

Anti-Pattern Fixes

Anti-PatternFix Strategy
LLM tell-talesReplace with plain language
Options without picksAdd recommendation with reasoning
Vague activationAdd specific tools/terms to "Use when:"
Missing sourcesAdd citation or move to sources.md
Tutorial contentCut it, Claude knows basics
Generic adviceMake specific or cut entirely

LLM tell-tale replacements:

AvoidUse Instead
delveexplore, examine, look at
leverageuse
robustreliable, solid
comprehensivecomplete, full
myriadmany
utilizeuse
facilitatehelp, enable

Em dash fixes:

PatternFix
X — Y (explanation)X: Y or X. Y
X — Y (aside)X (Y) or rewrite
X — Y (contrast)X, but Y or X; Y

False dichotomy fixes:

PatternProblemFix
"isn't X, it's Y"Usually both are trueState Y directly
"not about X, it's about Y"False exclusion"Y" (remove X clause)

Run falsification: Can it be both X and Y? If yes, remove the dichotomy.

Gate-Specific Fixes

Content Quality (Gate 1)

Problem: Teaches basics Claude knows

# Before
## Installation
First, install the package:
npm install foo

Fix: Cut tutorial content, focus on non-obvious

# After
## Gotchas
The default config assumes ESM. For CommonJS, set `type: "commonjs"` in package.json.

Problem: Options without picks

# Before
You could use A, B, or C for this task.

Fix: Make a decision with reasoning

# After
Use A for most cases.

| Situation | Use | Why |
|-----------|-----|-----|
| Default | A | Fastest, best maintained |
| Legacy support | B | Works with Node 14 |
| Edge cases | C | Only if you need X |
Transparency (Gate 2)

Problem: Unsourced claim

# Before
This approach is 10x faster.

Fix: Add source

# After
This approach is 10x faster ([Benchmark 2024](https://example.com/benchmark)).

Problem: No reasoning shown

# Before
Use tokio for async.

Fix: Add WHY

# After
Use tokio for async.

**Why:** De facto standard, used by Cloudflare/Discord/AWS. Multi-threaded by default, excellent ecosystem (tower, hyper, axum built on it).
Control (Gate 3)

Problem: Rigid mandate

# Before
Always use X. Never use Y.

Fix: Decision framework

# After
| Context | Use | Why |
|---------|-----|-----|
| High throughput | X | Better under load |
| Simple scripts | Y | Less overhead |
| Mixed | X | Future-proof |
Activation (Gate 5)

Problem: Vague triggers

# Before
description: "Helps with code"

Fix: Specific tools/domains

# After
description: "Rust async patterns. Use when: tokio, async-std, futures, Streams, spawning tasks, async traits."

Structural Fixes

Missing sources.md:

  1. Create references/sources.md
  2. Move all URLs from SKILL.md to sources.md
  3. Group by category
  4. Add access dates

SKILL.md too long (> 500 lines):

  1. Move detailed content to references/
  2. Keep SKILL.md as overview + navigation
  3. Use "Load [file.md] when [condition]" pattern

Missing plugin.json:

{
  "name": "plugin-name",
  "description": "One-line description",
  "version": "1.0.0"
}

Process

1. Parse Evaluator Output

Extract:

  • Current gate scores
  • List of issues (prioritized)
  • Specific line numbers
  • Anti-patterns found

2. Triage

Group by fixability:

CategoryAction
Auto-fixableApply fix immediately
Needs contextRead surrounding code first
Needs decisionFlag for human review

3. Fix in Priority Order

Critical issues → Major issues → Minor issues

For each issue:

  1. Read the context (5 lines before/after)
  2. Apply minimal fix
  3. Verify fix doesn't break anything
  4. Log what was changed

4. Re-Verify

After all fixes:

  1. Check SKILL.md still < 500 lines
  2. Verify frontmatter intact
  3. Ensure no broken references
  4. Run anti-pattern regex again

5. Report Changes

Document what was fixed:

## Optimization Report: [plugin-name]

### Fixes Applied

| Issue | Location | Fix | Status |
|-------|----------|-----|--------|
| LLM tell-tale "leverage" | SKILL.md:42 | Changed to "use" | ✅ |
| Missing source | SKILL.md:87 | Added citation | ✅ |
| Vague activation | frontmatter | Added specific triggers | ✅ |

### Deferred to Human

| Issue | Reason |
|-------|--------|
| "Should we include X feature?" | Requires domain decision |

### Expected Score Change

| Gate | Before | After (est.) |
|------|--------|--------------|
| Content | 1 | 2 |
| Activation | 1 | 3 |
| **Total** | 10 | 13 |

### Recommendation

[Ready for re-evaluation / Needs human input on N items]

Escalation Rules

Escalate to human when:

SituationWhy
Contradictory requirementsCan't satisfy both
Missing domain expertiseDon't know what's correct
Major structural change neededBeyond "fix" scope
Unclear what to cutContent decisions need owner
Sources can't be foundNeed human to verify claims

Don't escalate:

  • Mechanical fixes (typos, formatting)
  • Clear anti-patterns
  • Missing boilerplate (plugin.json, sources.md)
  • LLM tell-tale replacements

Principles

  • Surgical, not sweeping: minimal changes to fix the issue
  • Preserve intent: don't change what the plugin does
  • One issue at a time: atomic fixes, easy to review
  • Verify after each: don't stack broken fixes
  • Know your limits: escalate domain decisions

Sponsors

Details

Marketplace
yzavyas/claude-1337
Source
plugins/1337-extension-builder
Author
yzavyas
Category
Development
License
MIT
Keywords
skills, meta, documentation, best-practices

More from yzavyas/claude-1337

All 12