agent creation methodology

step 1: define agent purpose

  critical questions:
    [1] what SPECIFIC problem does this agent solve?
    [2] who is the target user?
    [3] what makes this different from existing agents?
    [4] what expertise does it provide?

  red flags:
    [x] vague purpose ("helps with stuff")
    [x] overlaps heavily with existing agent
    [x] too broad ("does everything")
    [x] no clear use case

  good agent purposes:
    [ok] "python cli expert - builds command-line tools with llm integration"
    [ok] "kollabor meta-agent - creates new agents and skills"
    [ok] "technical writer - produces documentation"
    [ok] "coder - implements features with investigation-first approach"

step 2: identify core capabilities

  agent capabilities should be:
    - concrete and actionable
    - domain-specific
    - complementary to existing agents

  example: python-cli-llm-dev agent
    capabilities:
      [ok] argparse/click/typer expertise
      [ok] async llm api integration patterns
      [ok] rich/textual ui development
      [ok] cli testing with pytest
      [ok] packaging and distribution
      [ok] error handling and logging

step 3: design system prompt

  system prompt structure:
    [1] header:      agent identity and version
    [2] philosophy:  core principles and mindset
    [3] context:     dynamic session information via <trender>
    [4] expertise:   domain knowledge and capabilities
    [5] patterns:    response templates and workflows
    [6] tools:       file operations and terminal usage
    [7] examples:    concrete usage scenarios
    [8] constraints: limitations and best practices
    [9] formatting:  terminal output rules

  system prompt best practices:
    [ok] start with clear identity statement
    [ok] define core philosophy (1-2 sentences max)
    [ok] use <trender> for dynamic context
    [ok] provide concrete examples, not abstract theory
    [ok] include response templates for common scenarios
    [ok] specify tool usage patterns
    [ok] set clear boundaries and constraints
    [ok] enforce terminal-friendly formatting

step 4: create agent directory structure

  directory layout:
    agents/
      <agent-name>/
        system_prompt.md    (required: agent system prompt)
        README.md           (optional: documentation)
        examples/           (optional: usage examples)

  naming conventions:
    [ok] lowercase with hyphens: python-cli-llm-dev
    [ok] descriptive but concise: kollabor, coder, technical-writer
    [ok] avoid redundant suffixes: "agent", "specialist"

step 5: implement and test

  validation checklist:
    [ ] system_prompt.md created and complete
    [ ] agent purpose clearly documented
    [ ] response templates provided
    [ ] examples demonstrate core capabilities
    [ ] terminal formatting rules included
    [ ] dynamic context rendering works
    [ ] no overlap with existing agents

