/new-skill-builder

name: new-skill
description: "Install, create, scaffold, and validate new skills in Codex-first skill folders such as .codex/skills/ and .agents/skills/. Use when adding a skill from a URL, GitHub repo, zip file, or markdown content, or when creating a new skill from scratch. Also use for validating existing skills, fixing registration issues, or restructuring agent skill folders."

New Skill Installer & Scaffolder

Overview

This skill helps you install, create, and manage skills in your Codex-first `.codex/skills/` or `.agents/skills/` directory. It handles the full lifecycle: scaffolding new skills from scratch, installing skills from external sources, validating skill structure, and troubleshooting registration issues.

---

Workflow 1: Create a New Skill From Scratch

When the user wants to create a brand new skill:

1. **Ask for details** (if not provided):

• Skill name (lowercase, hyphenated, e.g. `api-tester`)
• What it should do (purpose)
• When it should trigger (contexts)
• Whether it needs scripts, references, or assets

2. **Scaffold the folder structure:**

SKILL_NAME="the-skill-name"
PROJECT_DIR="$(pwd)"
SKILL_DIR="${PROJECT_DIR}/.codex/skills/${SKILL_NAME}"

mkdir -p "${SKILL_DIR}"
mkdir -p "${SKILL_DIR}/scripts"
mkdir -p "${SKILL_DIR}/references"
mkdir -p "${SKILL_DIR}/assets"

3. **Generate the SKILL.md** with proper frontmatter:

---
name: {skill-name}
description: "{What it does}. Use when {trigger conditions}. Handles {capabilities}."
---

# {Skill Title}

## Overview
{One paragraph purpose statement}

## Instructions
1. {Step-by-step instructions}

## Examples
### Example 1
**Input:** "{example user request}"
**Action:** {what the skill does}
**Output:** {expected result}

## Error Handling
- {How to handle failures}

## Notes
- {Caveats and edge cases}

4. **Validate the skill** (run Workflow 4 below)

5. **Report back** with the file tree and confirmation it's registered.

---

Workflow 2: Install a Skill From External Source

When the user provides a URL, GitHub repo, zip file, or raw markdown:

From a GitHub Repository URL

REPO_URL="$1"
SKILL_NAME="$2"  # Extract from repo name if not given
SKILL_DIR=".codex/skills/${SKILL_NAME}"

# Clone just the skill content
git clone --depth 1 "${REPO_URL}" "/tmp/${SKILL_NAME}-clone"

# Find the SKILL.md
SKILL_FILE=$(find "/tmp/${SKILL_NAME}-clone" -name "SKILL.md" -type f | head -1)

if [ -z "$SKILL_FILE" ]; then
  echo "ERROR: No SKILL.md found in repository."
  echo "This repo may not be a valid AgentSkills package."
  exit 1
fi

# Get the skill's parent directory (contains SKILL.md + siblings)
SKILL_SRC=$(dirname "$SKILL_FILE")

# Copy to .codex/skills/
mkdir -p "${SKILL_DIR}"
cp -r "${SKILL_SRC}/"* "${SKILL_DIR}/"

# Cleanup
rm -rf "/tmp/${SKILL_NAME}-clone"

echo "Installed ${SKILL_NAME} to ${SKILL_DIR}"

From Raw Markdown Content

If the user pastes or uploads a SKILL.md file:

1. Extract the `name` field from YAML frontmatter 2. Create `.codex/skills/{name}/SKILL.md` 3. Write the content 4. Check if it references external files (scripts/, references/, assets/) 5. Warn the user about any missing referenced files

From a Zip File

ZIP_FILE="$1"
TEMP_DIR="/tmp/skill-install-$$"

mkdir -p "$TEMP_DIR"
unzip -q "$ZIP_FILE" -d "$TEMP_DIR"

# Find SKILL.md (may be nested in a folder)
SKILL_FILE=$(find "$TEMP_DIR" -name "SKILL.md" -type f | head -1)

if [ -z "$SKILL_FILE" ]; then
  echo "ERROR: No SKILL.md found in zip."
  exit 1
fi

SKILL_SRC=$(dirname "$SKILL_FILE")
SKILL_NAME=$(grep "^name:" "$SKILL_FILE" | head -1 | sed 's/name: *//' | tr -d '"' | tr ' ' '-' | tr '[:upper:]' '[:lower:]')

if [ -z "$SKILL_NAME" ]; then
  SKILL_NAME=$(basename "$SKILL_SRC")
fi

SKILL_DIR=".codex/skills/${SKILL_NAME}"
mkdir -p "$SKILL_DIR"
cp -r "$SKILL_SRC/"* "$SKILL_DIR/"

rm -rf "$TEMP_DIR"
echo "Installed ${SKILL_NAME} to ${SKILL_DIR}"

---

Workflow 3: Install the Uploaded MCP Builder Skill

When the user wants to install the `mcp-builder` skill specifically:

1. Create the directory structure:

mkdir -p .codex/skills/mcp-builder/reference

2. Copy or create the SKILL.md from the user's uploaded file into `.codex/skills/mcp-builder/SKILL.md`

3. Note that the SKILL.md references these files that need to be populated:

• `{baseDir}/reference/mcp_best_practices.md`
• `{baseDir}/reference/python_mcp_server.md`
• `{baseDir}/reference/node_mcp_server.md`
• `{baseDir}/reference/evaluation.md`

4. Either fetch them from the source repo (if URL provided) or create stub files:

for ref in mcp_best_practices python_mcp_server node_mcp_server evaluation; do
  if [ ! -f ".codex/skills/mcp-builder/reference/${ref}.md" ]; then
    echo "# ${ref}" > ".codex/skills/mcp-builder/reference/${ref}.md"
    echo "" >> ".codex/skills/mcp-builder/reference/${ref}.md"
    echo "TODO: Populate with content from the original skill repository." >> ".codex/skills/mcp-builder/reference/${ref}.md"
    echo "Source: https://github.com/ComposioHQ/awesome-claude-skills/tree/main/mcp-builder/reference" >> ".codex/skills/mcp-builder/reference/${ref}.md"
  fi
done

5. Warn the user that stub reference files need real content for full functionality.

---

Workflow 4: Validate Skills

Run these checks on any skill to ensure it will register properly:

Validation Checklist

SKILL_DIR="$1"  # e.g., .codex/skills/my-skill

# 1. Check SKILL.md exists
if [ ! -f "${SKILL_DIR}/SKILL.md" ]; then
  echo "FAIL: No SKILL.md found in ${SKILL_DIR}"
  exit 1
fi

# 2. Check frontmatter exists
if ! head -1 "${SKILL_DIR}/SKILL.md" | grep -q "^---"; then
  echo "FAIL: SKILL.md must start with --- (YAML frontmatter)"
  exit 1
fi

# 3. Check name field
if ! grep -q "^name:" "${SKILL_DIR}/SKILL.md"; then
  echo "FAIL: Missing 'name:' in frontmatter"
  exit 1
fi

# 4. Check description field
if ! grep -q "^description:" "${SKILL_DIR}/SKILL.md"; then