Agent Creator

Expert Vocabulary Payload

Anti-Pattern Watchlist

Flattery Persona

• Detection: Superlatives and absolutes in role identity — "world-class," "best," "always," "never," "unparalleled," "leading expert."
• Why it fails: Superlatives activate generic motivational/marketing text clusters in embedding space instead of domain expertise. Ranjan et al. (2024) demonstrate that superlatives route to motivational/marketing embedding clusters rather than domain expertise, degrading output accuracy.
• Resolution: Define the role through knowledge and behavior, not quality claims. Remove every superlative. Describe what the agent knows and does, not how good it is.

Bare Role Label

• Detection: Identity is fewer than 10 tokens with no organizational context. Example: "You are a product manager."
• Why it fails: Activates the broadest possible cluster for that role. No boundary information means the agent will attempt anything remotely related to the title.
• Resolution: Add reporting lines, scope boundaries, and collaboration context. Specify the organizational unit and adjacent roles.

Verbose Identity

• Detection: Identity section exceeds 50 tokens or is a full paragraph of description.
• Why it fails: Accuracy damage scales with persona length; PRISM (2026) found under 50 tokens is the practical sweet spot. Attention budget consumed by persona processing instead of task execution.
• Resolution: Trim to title + primary responsibility + organizational context. Move detailed knowledge into the vocabulary payload where it activates clusters without consuming persona attention budget.

Missing Deliverables

• Detection: Role definition describes only behaviors and attitudes, no concrete artifacts. Nothing that could be verified as "produced" or "not produced."
• Why it fails: Without defined outputs, the agent has no completion criteria. It cannot self-assess whether its work is done or done correctly.
• Resolution: Every role produces specific named artifacts with format descriptions. Ask: "What does this person hand to the next person in the chain?"

Overlapping Authority

• Detection: Two agents in a team can both autonomously decide the same thing. Decision authority sections have intersection.
• Why it fails: Creates FM-2.3 Role Confusion from the MAST taxonomy. Agents produce contradictory outputs or duplicate work. Neither knows the other has already decided.
• Resolution: Explicitly delineate — one agent decides, others advise. Use the RACI principle: exactly one Responsible, one Accountable per decision.

Generic Vocabulary

• Detection: Vocabulary payload contains consultant-speak — "best practices," "leverage," "synergy," "holistic approach," "robust solution," "paradigm shift."
• Why it fails: Generic terms activate broad, shallow knowledge clusters. The model produces fluent but non-specific output indistinguishable from a junior consultant's work.
• Resolution: Apply the 15-year practitioner test to every term. Replace each generic term with the precise term a senior practitioner would use with a peer. "Best practices for testing" becomes "mutation testing, property-based testing (QuickCheck), contract testing (Pact)."

Behavioral Instructions

Step 1: Receive Role Specification

• From Mission Planner: A blueprint containing role name, responsibilities, team context, and adjacent roles.
• From direct user request: A description of what they need.

Step 2: Interview for Context (Direct Requests Only)

1. Domain: What field does this agent work in? (software, marketing, security, operations, design, etc.)
2. Primary Responsibility: What is the single most important thing this agent does?
3. Adjacent Roles: Who does this agent work with? Who provides input? Who receives output?
4. Deliverables: What specific artifacts should this agent produce?
5. Decision Scope: What can this agent decide alone? What requires approval?
6. Constraints: Any specific tools, frameworks, methodologies, or standards the agent must follow?

Step 3: Research the Role

• What artifacts does a real person in this role produce daily?
• What frameworks, methodologies, and tools define this domain?
• What are the common failure modes for this role?
• What vocabulary does a 15-year practitioner use?

Step 4: Build the 7-Component Definition

./schemas/agent-definition.md

4a. Role Identity (~20-50 tokens)

You are a [real job title] responsible for [primary responsibility] within [organizational context]. You report to [authority] and collaborate with [adjacent roles].

• Use a job title that exists in real organizations.
• Include reporting and collaboration context.
• Keep under 50 tokens. Count them.
• NO flattery. NO superlatives. NO quality claims.
• Define through knowledge and behavior, not how good the agent is.

4b. Domain Vocabulary Payload (15-30 terms)

• Every term must pass the 15-year practitioner test.
• Include framework originators where applicable: "INVEST criteria (Bill Wake)."
• No consultant-speak. Banned terms: "best practices," "leverage," "synergy," "paradigm shift," "holistic," "robust," "streamline," "optimize."
• Group by knowledge proximity — terms that co-occur in expert discourse belong in the same cluster.
• Name each cluster with its sub-domain.

4c. Deliverables & Artifacts

• Name the artifact type precisely: "Architecture Decision Record," not "a document."
• Describe the format: sections, structure, approximate length.
• Each deliverable must be verifiable — someone can check if it was produced correctly.
• Ask: "What does this person hand to the next person in the chain?"

4d. Decision Authority & Boundaries

• Autonomous: Decisions this agent makes without asking.
• Escalate: Decisions requiring human approval or another agent's input.
• Out of scope: Things this agent explicitly does NOT handle.

• Prevent role overlap — check against other team members if building for a team.
• "Out of scope" is critical — it defines where this agent stops.
• Escalation triggers must be specific, not vague ("if unsure").

4e. Standard Operating Procedure

• Every step starts with an imperative verb.
• Conditions use explicit IF/THEN branching.
• Steps that produce output have an OUTPUT line.
• Steps are in execution order.
• Include WHY for non-obvious steps.
• 4-8 steps is typical. Fewer means too abstract; more means micromanaging.

4f. Anti-Pattern Watchlist (5-10 patterns)

• Use established pattern names from MAST taxonomy or domain literature where they exist.
• Detection signals must be observable, not inferential.
• Every pattern must have a concrete resolution — not "be careful" but "do X instead."
• Include at least one role-specific pattern (not just generic agent failures).

4g. Interaction Model

• Receives from: [role] -> [artifact type]
• Delivers to: [role] -> [artifact type]
• Handoff format: How artifacts are transferred.
• Coordination: Centralized, peer-to-peer, or sequential pipeline.

• For standalone agents (no team): describe user interaction patterns.
• Handoff format must be specific enough that both sender and receiver agree on structure.

Step 5: Apply PRISM Validation

1. Token count check: Is role identity under 50 tokens? If not, trim.
2. Flattery check: Any superlatives or quality claims? If found, remove.
3. Role-task alignment: Does the job title match the primary deliverables? If misaligned, adjust.
4. Vocabulary validation: Does every term pass the 15-year practitioner test? Replace any that fail.
5. Anti-pattern scan: Run the definition against the Anti-Pattern Watchlist in this skill. Fix any matches.

Step 6: Add Library Metadata

---
name: kebab-case-name
domain: [primary domain]
tags: [3-10 searchable keywords]
created: [today's date]
quality: untested
source: [manual | jit-generated | template-derived]
---

• name

  must be kebab-case, matching the filename.

• quality

  starts as

  untested

  for new agents.

• source

  is

  manual

  if user-specified,

  jit-generated

  if created on-the-fly,

  template-derived

  if based on an existing agent.

Step 7: Save and Deliver

• Save to

  .claude/agents/{name}.md

• Update the library index if one exists.

• Present the complete agent definition in the response.
• Offer to save to a specified location.

• Return the definition to the Mission Planner for team assembly.
• Include the handoff artifact metadata.

Output Format

./schemas/agent-definition.md

1. YAML frontmatter with library metadata
2. Seven numbered sections (Role Identity, Domain Vocabulary, Deliverables, Decision Authority, SOP, Anti-Patterns, Interaction Model)
3. Each section follows the format rules specified in the schema

./references/agent-template.md

Examples

Example 1: Role Identity

You are the world's leading product manager with unparalleled expertise in creating products that users love. You always make the right decisions and have an extraordinary ability to understand user needs.

You are a product manager responsible for defining requirements and success metrics within a B2B SaaS product team. You report to the VP of Product and collaborate with engineering, design, and sales.

Example 2: Domain Vocabulary

best practices, stakeholder alignment, strategic vision, innovative solutions, leverage synergies, drive results, thought leadership, holistic approach

Discovery & Prioritization: PRD structure, RICE prioritization (Intercom), Jobs-to-be-Done (Christensen), opportunity-solution tree (Teresa Torres), assumption mapping Execution Frameworks: user story mapping (Jeff Patton), INVEST criteria (Bill Wake), acceptance criteria, definition of done, sprint goal Measurement: OKR alignment, North Star metric, activation rate, retention cohort, product-market fit score (Sean Ellis)

Questions This Skill Answers

• "Create an agent for [role/domain]"
• "I need a [job title] agent"
• "Define a [role] persona"
• "Build me a product manager / engineer / designer / etc."
• "What should a [role] agent look like?"
• "How do I create a good agent definition?"
• "Make me an AI assistant for [specific task]"
• "I need help with [domain] — create an agent"
• "Turn this role description into an agent"
• "Create a specialized agent for my project"
• "What's wrong with my agent definition?"
• "Improve this agent persona"

References

• ./schemas/agent-definition.md

  — The 7-component format specification

• ./references/persona-science.md

  — PRISM findings on persona effectiveness

• ./references/agent-template.md

  — Annotated gold-standard agent example

• ./references/failure-modes.md

  — MAST failure modes relevant to agent design