Skip to main content

/component-create - Interactive Component Creation

Create new CODITECT framework components with proper templates, automatic registration, activation, and MoE classification.

System Prompt​

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. Check for --user flag — If present, resolve user-components directory from config
  2. Run the interactive script - Execute scripts/component-create.sh
  3. Collect inputs - Component type, name, description, and metadata
  4. Execute 4-step workflow:
    • Create component from template (in user dir if --user, else system dir)
    • Update component inventory
    • Register and activate in framework
    • Classify with MoE
  5. Report results - Show created file path and registration status

User component path resolution (for --user flag):

import json
from pathlib import Path

def get_user_components_dir():
    """Resolve the user-components directory from config."""
    config_path = Path.home() / "PROJECTS" / ".coditect-data" / "user-components-config.json"
    if config_path.exists():
        with open(config_path) as f:
            return Path(json.load(f)['path'])
    # Default fallback
    return Path.home() / "PROJECTS" / ".coditect-data" / "user-components"

REQUIRES CONFIRMATION: This command creates new files and updates framework registries.

Usage​

/component-create                          # Interactive mode
/component-create agent my-agent           # Create agent (system)
/component-create skill my-skill           # Create skill (system)
/component-create command my-command       # Create command (system)
/component-create --user agent my-agent    # Create agent (user-owned)
/component-create --user skill my-skill    # Create skill (user-owned)

User-Owned Components (ADR-180)​

The --user flag creates components in the user's personal component directory instead of the protected framework. User components:

  • Persist across framework updates (stored outside protected core)
  • Are discoverable via _user symlinks and platform.db indexing
  • Have component_origin: user in the database (vs system or product)

Path resolution (priority order):

  1. --user-components-dir config from ~/.coditect-data/user-components-config.json
  2. Default: ~/.coditect-data/user-components/

The install script creates this config during setup (Step 18). Users can choose a custom location during installation or pass --user-components-dir to the install script.

# Read user-components location
python3 -c "import json; print(json.load(open('$HOME/PROJECTS/.coditect-data/user-components-config.json'))['path'])"

When --user is specified, the component is created in <user-components-dir>/{type}/ instead of <coditect-core>/{type}/.

Supported Component Types​

TypeSystem DirectoryUser DirectoryFile PatternDescription
agentagents/<user-dir>/agents/{name}.mdAI agent definition
skillskills/{name}/<user-dir>/skills/{name}/SKILL.mdReusable skill
commandcommands/<user-dir>/commands/{name}.mdSlash command
hookhooks/<user-dir>/hooks/{name}.mdEvent trigger
scriptscripts/N/A{name}.py or .shAutomation script
workflowworkflows/N/A{name}.yamlWorkflow definition

Stub / Redirect Components​

Create a redirect stub when a component has been relocated to another repository. Stubs ensure framework discovery continues to work while directing users to the new location.

Usage​

# Create a stub for a relocated skill
/component-create skill pdf-to-markdown --stub --relocated-to coditect-research-continuum --relocated-path src/pipeline/

# Create a stub for a relocated command
/component-create command udom-navigator --stub --relocated-to coditect-research-continuum --relocated-path src/tools/

# Create a deprecation stub (no target repo)
/component-create agent old-agent --stub --deprecated --reason "Superseded by new-agent"

Stub Options​

OptionRequiredDescription
--stubYesCreate a redirect stub instead of a full component
--relocated-toFor relocationTarget repository name
--relocated-pathNoPath within target repo (default: same as source)
--deprecatedFor deprecationMark as deprecated (no target repo)
--reasonNoReason for relocation/deprecation

Stub Template​

All stubs are created with this standard structure:

---
title: "{Name} (Relocated)"
component_type: {type}
version: 1.0.0
status: relocated           # or "deprecated"
relocated_to: {target-repo}
relocated_date: "{date}"
relocated_path: "{path-in-target-repo}"
original_path: "{original-path}"
reason: "{reason}"
summary: "RELOCATED — see {target-repo}"
keywords: [relocated, stub, {original-keywords}]
created: "{original-created-date}"
updated: "{date}"
---
# {Component Name}

> **This component has been relocated to [`{target-repo}`](https://github.com/coditect-ai/{target-repo}).**
>
> **New location:** `{target-repo}/{relocated-path}`
> **Relocated:** {date}
> **Reason:** {reason}

This stub exists so that framework discovery (skill catalog, command index,
component search) continues to find this component and directs users to its new home.

## Usage

See the [{target-repo} README](https://github.com/coditect-ai/{target-repo})
for current usage instructions.

Stub Behavior in Framework​

SystemBehavior with Stub
Skill catalog (/search-skills)Shows component with [RELOCATED] badge
Command index (/search-commands)Shows command with redirect message
Component search (/component-search)Includes in results with relocated status
Component indexer (component-indexer.py)Indexes with status: relocated
MoE classifierSkips classification (preserves original metadata)

Examples​

# Create a new agent
/component-create agent pricing-analyst
# Creates: agents/pricing-analyst.md

# Create a new skill
/component-create skill api-testing
# Creates: skills/api-testing/SKILL.md

# Create a new command
/component-create command deploy
# Creates: commands/deploy.md

# Create a new hook
/component-create hook pre-commit
# Creates: hooks/pre-commit.md

# Create a Python script
/component-create script data-processor --lang python
# Creates: scripts/data-processor.py

# Create a workflow
/component-create workflow ci-pipeline
# Creates: workflows/ci-pipeline.yaml

Interactive Prompts​

The script will prompt for:

  1. Component type (required)

    • Select from: agent, skill, command, hook, script, workflow

  2. Component name (required)

    • Kebab-case name (e.g., my-component)
    • No spaces or special characters

  3. Summary (required)

    • One-line description of what the component does

  4. Additional metadata (optional)

    • Keywords, tags, version, audience

What It Does​

Step 1: Create from Template​

# For system components (default):
#   Generates in coditect-core/{type}/ with proper frontmatter
# For user components (--user flag):
#   Reads user-components-config.json for target directory
#   Generates in <user-dir>/{type}/ with component_origin: user
# Uses templates from templates/components/

Step 2: Update Inventory​

python3 scripts/update-component-counts.py
# Updates config/component-counts.json

Step 3: Register and Activate in Framework​

python3 scripts/core/ensure_component_registered.py
# Registers and activates in:
#   - SQLite platform.db (ADR-118 Tier 1)
#   - config/framework-registry.json
#   - config/component-activation-status.json

Step 4: Classify with MoE​

python3 scripts/moe_classifier/classify.py <component-path> --update-frontmatter
# Adds MoE frontmatter:
#   - moe_confidence, moe_classified
#   - Enhanced keywords and tags

Component Templates​

Agent Template​

---
title: {Name}
component_type: agent
version: 1.0.0
audience: customer
status: active
summary: {summary}
keywords: []
tokens: ~1500
created: '{date}'
agent_type: specialist
domain: []
moe_role: specialist
invocation_pattern: /agent {name} '<task>'
model: sonnet
tools: Read, Write, Edit, Grep, Glob
---
# {Name} Agent

{Description and instructions...}

Skill Template​

---
title: {Name}
component_type: skill
version: 1.0.0
status: active
summary: {summary}
keywords: []
created: '{date}'
---
# {Name} Skill

## When to Use
{Triggers...}

## Steps
{Instructions...}

Command Template​

---
title: {Name}
component_type: command
version: 1.0.0
status: active
summary: {summary}
invocation: /{name}
---
# /{name} - {Title}

{Description and usage...}

Script Location​

scripts/component-create.sh

Direct Script Usage​

# Interactive mode
./scripts/component-create.sh

# With arguments
./scripts/component-create.sh --type agent --name my-agent --summary "Does something"

# Non-interactive
./scripts/component-create.sh \
  --type skill \
  --name api-testing \
  --summary "API testing patterns" \
  --non-interactive

Prerequisites​

  • Write access to coditect-core directory
  • Python 3.10+ for registration scripts
  • Templates in templates/components/ (optional, uses defaults)

Success Output​

======================================================
  Component Created Successfully!
======================================================

Type: agent
Name: pricing-analyst
Path: agents/pricing-analyst.md

Completed steps:
  ✓ Step 1: Created from template
  ✓ Step 2: Updated component inventory
  ✓ Step 3: Registered and activated in framework
  ✓ Step 4: Classified with MoE

Component counts updated:
  agents: 148 -> 149

Next steps:
  1. Edit agents/pricing-analyst.md to customize
  2. Run /agent pricing-analyst "test task" to verify

Rollback​

If component creation fails:

# Remove created file
rm <component-path>

# Re-run inventory update
python3 scripts/update-component-counts.py

# Re-run registration (no args = register all)
python3 scripts/core/ensure_component_registered.py

Completion Checklist​

Before marking complete:

  • Component file created
  • Inventory counts updated
  • Framework registration complete
  • MoE classification applied
  • Confirmation displayed

Failure Indicators​

This command has FAILED if:

  • ❌ Template not found
  • ❌ Write permission denied
  • ❌ Registration script error
  • ❌ MoE classification failed

When NOT to Use​

Do NOT use when:

  • Similar component already exists (extend instead)
  • Not sure what type to create (research first)
  • Component name not finalized

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Create without searchDuplicatesCheck existing components first
Skip registrationUndiscoverableAlways complete 4-step workflow
Generic namesConfusionUse descriptive kebab-case names

Principles​

This command embodies:

  • #1 Recycle, Extend, Re-Use - Search before creating
  • #3 Complete Execution - All 4 steps required
  • #4 Separation of Concerns - One component, one purpose

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Action Policy​

<default_behavior> This command requires confirmation before:

  • Creating new component files
  • Updating framework registries
  • Modifying component counts

Shows a preview of the component to be created. </default_behavior>

After execution, verify: - Component file exists at expected path - Component counts updated in config/component-counts.json - Component registered in framework-registry.json - Component activated in component-activation-status.json - MoE classification applied (moe_confidence > 0.85)

Version: 1.2.0 Created: 2026-01-03 Updated: 2026-02-12 Author: CODITECT Team

Changelog​

VersionDateChanges
1.2.02026-02-12ADR-180: --user flag for user-owned components. Reads path from user-components-config.json. Components created in user dir with component_origin: user.
1.1.02026-02-11Stub/redirect component creation for relocated and deprecated components
1.0.02026-01-03Initial interactive component creation