Graduating Creations

Promote to production

Graduating Smith Creations

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

When a Smith-created tool proves valuable, you may want to make it permanent - part of an addon, extension, or framework that others can use. This guide covers when and how to graduate Smith creations from project-local assets to permanent AIWG components.

When to Graduate

Keep it project-local when:

  • It's specific to your project's needs
  • It references project-specific paths, APIs, or configurations
  • You're still iterating on the design
  • It's a one-off utility

Graduate to permanent when:

  • You're copying it between projects
  • Others ask for the same capability
  • It solves a general problem (not project-specific)
  • The design has stabilized through use

Graduation Paths

Smith CreationGraduates ToLocation
ToolSmith scriptAddon utility`agentic/code/addons/<name>/tools/`
MCPSmith serverMCP tool in AIWG server`src/mcp/tools/`
AgentSmith agentFramework agent`agentic/code/frameworks/<framework>/agents/`
SkillSmith skillFramework skill`agentic/code/frameworks/<framework>/skills/`
CommandSmith commandFramework command`agentic/code/frameworks/<framework>/commands/`

Step-by-Step: Graduating a ToolSmith Script

1. Identify the Candidate

# Your project-local tool
.aiwg/smiths/toolsmith/scripts/find-security-issues.sh
.aiwg/smiths/toolsmith/tools/find-security-issues.yaml

2. Generalize the Implementation

Remove project-specific assumptions:

# Before: hardcoded paths
grep -r "password" /home/user/myproject/src/

# After: parameterized
grep -r "$PATTERN" "${TARGET_DIR:-./src/}"

3. Create an Addon

Use AIWG to complete this documented outcome: 3. Create an Addon
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

4. Move the Tool

# Copy to addon
cp .aiwg/smiths/toolsmith/scripts/find-security-issues.sh \
   agentic/code/addons/security-tools/tools/

# Update the addon manifest

5. Add to Addon Manifest

# agentic/code/addons/security-tools/addon.json
{
  "name": "security-tools",
  "version": "1.0.0",
  "tools": [
    {
      "name": "find-security-issues",
      "path": "tools/find-security-issues.sh",
      "description": "Scan for common security issues"
    }
  ]
}

Step-by-Step: Graduating an MCPSmith Server

1. Identify Value

Your MCP server is used across multiple projects or solves a general problem.

2. Extract and Generalize

# From project-local
.aiwg/smiths/mcpsmith/implementations/github-analyzer/

# Review for hardcoded values
grep -r "hardcoded\|specific\|my-" .aiwg/smiths/mcpsmith/implementations/github-analyzer/

3. Option A: Add to AIWG MCP Server

For tools that should be available to all AIWG users:

// src/mcp/tools/github-analyzer.mjs
export const githubAnalyzerTool = {
  name: 'analyze-github-repo',
  description: 'Analyze a GitHub repository',
  inputSchema: { /* ... */ },
  handler: async (args) => { /* ... */ }
};

Register in `src/mcp/server.mjs`.

3. Option B: Create Standalone MCP Package

For specialized tools that shouldn't be in the core:

# Create new package
mkdir -p packages/mcp-github-analyzer
cp -r .aiwg/smiths/mcpsmith/implementations/github-analyzer/* packages/mcp-github-analyzer/

# Publish separately
cd packages/mcp-github-analyzer
npm publish

Step-by-Step: Graduating Agentic Smiths

AgentSmith → Framework Agent

1. Copy the definition:

   cp .claude/agents/accessibility-reviewer.md \
      agentic/code/frameworks/sdlc-complete/agents/

2. Add metadata for deployment:

   ---
   name: accessibility-reviewer
   description: Reviews code for WCAG accessibility issues
   model: sonnet
   tools: Read, Glob, Grep
   category: analysis
   ---

3. Update framework manifest to include the new agent.

4. Test deployment:

Use AIWG to complete this documented outcome: 4. Test deployment
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

SkillSmith → Framework Skill

1. Move skill directory:

   cp -r .claude/skills/json-yaml-converter/ \
      agentic/code/frameworks/sdlc-complete/skills/

2. Verify SKILL.md format matches framework conventions.

3. Add to framework's skills manifest.

CommandSmith → Framework Command

1. Copy command:

   cp .claude/commands/lint-fix.md \
      agentic/code/frameworks/sdlc-complete/commands/

2. Ensure frontmatter includes required fields:

   ---
   description: Run linter with auto-fix
   category: development
   argument-hint: "<target> [the fix option]"
   allowed-tools: Bash, Read, Write
   ---

3. Test with deployment:

Use AIWG to complete this documented outcome: 3. Test with deployment
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Choosing the Right Home

Addon (Standalone Utility)

Best for:

  • General-purpose tools not tied to a specific workflow
  • Utilities that work with any framework
  • Small, focused capabilities
Use AIWG to complete this documented outcome: Best for: - General-purpose tools not tied to a specific workflow - Utilities that work with any framework - Small, focused capabilities
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Extension (Framework Enhancement)

Best for:

  • Capabilities that extend a specific framework
  • Domain-specific additions (GDPR for SDLC, FTC for Marketing)
  • 5-20 agents/commands that form a cohesive set
Use AIWG to complete this documented outcome: Best for: - Capabilities that extend a specific framework - Domain-specific additions (GDPR for SDLC, FTC for Marketing) - 5-20 agents/commands that form a cohesive set
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Framework Contribution

Best for:

  • Core capabilities everyone should have
  • Bug fixes or improvements to existing agents
  • New commands that fit the framework's mission

Submit a PR to the main repository.

Testing Graduated Creations

Before graduating, ensure your creation works outside your project:

Use AIWG to complete this documented outcome: Before graduating, ensure your creation works outside your project
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Documentation Requirements

Graduated creations need:

1. README explaining purpose and usage 2. Examples showing common use cases 3. Test cases (if applicable) 4. Changelog entry noting the addition

Summary

StageLocationScopeEffort
Project-local`.aiwg/smiths/` or `.claude/`Your project onlyAutomatic (Smith creates)
Addon`agentic/code/addons/<name>/`Anyone who installsLow (scaffold + copy)
Extension`agentic/code/addons/<name>/`Framework users who opt-inMedium (design for reuse)
Framework`agentic/code/frameworks/<name>/`All framework usersHigher (PR + review)

The path from "I needed this tool" to "everyone can use this tool" is straightforward. Start with Smiths, prove the value, then graduate when it makes sense.

References