create-prompt-spec

Create Prompt Specification

Create a reusable prompt specification file under .agent/prompts/ using a reusable format.

References

• plugins/jx-local/skills/create-prompt-spec/reference/Prompt-Specification-Frameworks.md — STCO, CREATE, XML, and raw prompt specification frameworks.

Arguments

Argument	Flag	Required	Default	Notes
Prompt name	--name	Yes (unless --list)	—	kebab-case slug (e.g., incident-summary-spec). Prompted if missing.
Description	--description	Yes (unless --list)	—	One-line summary. Prompted if missing.
Tags	--tags	No	[]	Comma-separated, each tag must match ^[a-z0-9]+(-[a-z0-9]+)*$.
Framework	--framework	No	stco	One of stco, create, xml, raw.
Scaffold only	--scaffold-only	No	false	If set, use scaffold body instead of interactive body input.
List	--list	No	false	List existing prompt specs and exit.

---

Phase 1: Parse Arguments

1. Extract --name, --description, --tags, --framework, --scaffold-only, --list.
2. If --list is set → skip to List Mode.
3. If --name missing → ask: "What should this prompt spec be called? (kebab-case, e.g., incident-summary-spec)"
4. If --description missing → ask: "One-line description of this prompt spec:"
5. If --framework missing and --scaffold-only is set → ask: "Which framework should be used? (stco/create/xml/raw, default: stco)"
6. If --scaffold-only and --framework is not set → default stco.

List Mode

1. Run: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-creator.py" list
2. Parse the JSON array output. Display as table: | Name | Description | Tags |
3. If empty, display: "No prompt specs found in .agent/prompts/. Create one with /jx-local:create-prompt-spec."
4. Exit.

---

Phase 2: Validate

Run all validations sequentially. Halt on first failure.

Step 2a — Agent-side name pre-check (shell-safety gate)

Before any Bash call, verify name matches ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ and length <= 50.

Step 2b — Name format

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-creator.py" validate-name <name>

On failure (exit 1): display the JSON error from stderr, ask user for corrected name.

Step 2c — Tag validation

Each tag must match ^[a-z0-9]+(-[a-z0-9]+)*$. Validate agent-side. On failure: report invalid tag and expected format.

Step 2d — Description validation

Must be single-line, max 200 chars. Validate agent-side.

Step 2e — Pre-check collision (advisory)

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-creator.py" check-collision <name>

On collision (exit 1): display "Prompt spec '' already exists at . Edit it directly or choose a different name." and halt.

Step 2f — Framework validation

Framework must be exactly one of stco, create, xml, or raw. On invalid value: ask for corrected framework before continuing.

---

Phase 3: Collect Body

• If --scaffold-only: use the selected framework scaffold as the body (or raw placeholder).
• If not scaffold-only: ask: "Enter the prompt spec content (markdown):" and use user content.

STCO scaffold

# PROMPT SPECIFICATION: [Task Name]
# Version: 1.0.0 | Target Model: [e.g., GPT-5]

## 1. SYSTEM (Role & Constraints)
- **Persona/Role:** Act as [specific role, expert, or personality]
- **Safety & Guardrails:** [Boundaries and what to avoid]
- **Reasoning Level:** [Low | Medium | High]

## 2. TASK (Core Instruction)
- **Objective:** [Single-sentence objective]
- **Execution Steps:**
  1. [Step 1]
  2. [Step 2]
  3. [Step 3]

## 3. CONTEXT (Reference Data & Variables)
- **Dynamic Inputs:**
  - `{{VARIABLE_1}}`: [Description]
  - `{{VARIABLE_2}}`: [Description]
- **Background Information:** [Domain context and links]

## 4. OUTPUT (Format & Style)
- **Format:** [Markdown, JSON, table, etc.]
- **Tone & Voice:** [Concise, technical, empathetic]
- **Constraints:** [Length limits, style restrictions]

CREATE scaffold

# CREATE Prompt Spec: [Content Type]

| Element | Specification Instructions |
| :--- | :--- |
| **C**haracter (Role) | Act as [Expert Persona]. |
| **R**equest (Task) | [Action and expected output]. |
| **E**xamples (Few-Shot) | "Insert sample style and structure." |
| **A**udience & Tone | Target audience and tone. |
| **T**arget Constraints | Word count, format, exclusions. |

XML scaffold

<prompt_specification>
  <meta>
    <task_name>[Task Name]</task_name>
    <version>1.0.0</version>
    <target_engine>[Model]</target_engine>
  </meta>
  <system_prompt>
    <role>[Persona / Agent role]</role>
    <safety_and_rules>
      <rule>[Security and confidentiality rules]</rule>
      <rule>[Behavior constraints]</rule>
    </safety_and_rules>
  </system_prompt>
  <task_flow>
    <step id="1">Analyze user request.</step>
    <step id="2">Apply context and reference data.</step>
    <step id="3">Produce required output format.</step>
  </task_flow>
  <output_rules>
    <format>[JSON | Markdown | Text]</format>
    <tone>[Clear and direct]</tone>
  </output_rules>
</prompt_specification>

Raw scaffold

<!-- TODO: Write your prompt spec here -->

---

Phase 4: Confirm & Write

Step 4a — Display preview

## Planned Prompt Specification

File: .agent/prompts/<name>.md
Name: <name>
Description: <description>
Tags: <tags>
Framework: <framework>

--- Preview ---
---
name: <name>
description: '<description>'
tags: [<tags>]
---

<first 5 lines of body or full body if short>
--- End Preview ---

Proceed? (yes/no)

Do NOT proceed until user confirms.

Step 4b — Write via helper (file-based data transport)

1. Ensure prompt directory with: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-creator.py" ensure-dir
2. Parse path from JSON stdout into <prompts-dir>.
3. Write metadata and body to dotfiles in <prompts-dir>.
4. Invoke helper:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-creator.py" write \
  --metadata-file "<prompts-dir>/.<name>.metadata.json" \
  --body-file "<prompts-dir>/.<name>.body.md"

On success (exit 0): continue to Phase 5.
On failure (exit 1): show JSON error and stop. If field is collision, tell user the file was created between check and write.

---

Phase 5: Verify & Report

Step 5a — Verify

Read .agent/prompts/<name>.md and verify:

• File exists and is non-empty
• Starts with ---
• Contains name:, description:, tags: exactly once each
• tags: is YAML array
• Body is non-empty (unless --scaffold-only with explicit approval to skip body, if any)

Step 5b — Report

## Prompt Specification Created

File: .agent/prompts/<name>.md
Name: <name>
Description: <description>
Tags: <tags>
Framework: <framework>

Usage:
  cat .agent/prompts/<name>.md

List all specs:
  /jx-local:create-prompt-spec --list