new-skill

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):
2. Skill name (lowercase, hyphenated, e.g. api-tester)
3. What it should do (purpose)
4. When it should trigger (contexts)
5. Whether it needs scripts, references, or assets

1. 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"

1. 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}

1. Validate the skill (run Workflow 4 below)

1. 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

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

1. Note that the SKILL.md references these files that need to be populated:
2. {baseDir}/reference/mcp_best_practices.md
3. {baseDir}/reference/python_mcp_server.md
4. {baseDir}/reference/node_mcp_server.md
5. {baseDir}/reference/evaluation.md

1. 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

1. 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
  echo "FAIL: Missing 'description:' in frontmatter"
  exit 1
fi

# 5. Check description is quoted if it has special chars
DESC_LINE=$(grep "^description:" "${SKILL_DIR}/SKILL.md" | head -1)
if echo "$DESC_LINE" | grep -qE '[\[\]#]' && ! echo "$DESC_LINE" | grep -q '"'; then
  echo "WARN: Description contains special characters but is not quoted. This may cause YAML parse failures."
fi

# 6. Check line count
LINES=$(wc -l < "${SKILL_DIR}/SKILL.md")
if [ "$LINES" -gt 500 ]; then
  echo "WARN: SKILL.md is ${LINES} lines (recommended max: 500). Move detail to references/."
fi

# 7. Check for referenced files that don't exist
grep -oE '\{baseDir\}/[^ )"]+' "${SKILL_DIR}/SKILL.md" | while read -r ref; do
  REAL_PATH="${SKILL_DIR}/${ref#{baseDir}/}"
  if [ ! -f "$REAL_PATH" ]; then
    echo "WARN: Referenced file not found: ${ref} -> ${REAL_PATH}"
  fi
done

echo "PASS: Skill structure is valid."

Workflow 5: Restructure / Audit Agent Skill Folders

When the user wants to audit or fix their Codex-first skill setup:

1. Scan current structure:

echo "=== Current agent skill structure ==="
find .codex .agents skills -type f 2>/dev/null | head -50
echo ""
echo "=== Skills found ==="
find .codex/skills .agents/skills skills -name "SKILL.md" 2>/dev/null || echo "No skills directory found"

1. For each SKILL.md found, run validation (Workflow 4)

1. Check for common problems:
2. SKILL.md files not inside a named subfolder
3. Missing AGENTS.md at project root
4. Skills with duplicate names
5. Orphan folders (no SKILL.md inside)

1. Report findings and offer to fix issues.

1. If no Codex skill folder exists, scaffold one:

mkdir -p .codex/skills
mkdir -p .agent/playbooks

# Create starter AGENTS.md
cat > AGENTS.md << 'EOF'
# Project Configuration

## Stack
- TODO: List your tech stack

## Commands
- `npm run dev` — Start dev server
- `npm test` — Run tests
- `npm run build` — Production build

## Conventions
- TODO: Add your code style preferences
- TODO: Add your naming conventions

## Notes
- TODO: Add project-specific context for Codex
EOF

echo "Created .codex/skills and starter AGENTS.md"

Important Rules

1. Always validate after install — run the validation checklist on every new skill
2. Never overwrite without asking — if a skill folder already exists, confirm before replacing