new-skill

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

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

3. Check for common problems:

   • SKILL.md files not inside a named subfolder
   • Missing AGENTS.md at project root
   • Skills with duplicate names
   • Orphan folders (no SKILL.md inside)

4. Report findings and offer to fix issues.

5. 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
3. Quote all descriptions — use double quotes around description values as a default habit
4. Keep SKILL.md lean — under 500 lines, use references/ for depth
5. Test the trigger — after installing, suggest the user try a prompt that should activate the skill
6. Preserve existing structure — when restructuring, don't delete files without confirmation
7. Handle both project-local and global installs — ask the user which scope they want:
   • Project: ./.codex/skills/ or ./.agents/skills/
   • Global: ~/.codex/skills/
   • Hermes: the configured Hermes skills path, commonly under ~/.hermes/skills/

---

Error Handling

• Git clone fails: Check if URL is valid, suggest HTTPS vs SSH
• No SKILL.md in source: The source isn't a valid AgentSkills package — offer to create one from the content
• YAML parse error: Almost always unquoted special characters in description — auto-fix by quoting
• Skill doesn't trigger: Check description keywords match what users would actually say
• Skill triggers but fails: Check that referenced scripts/files exist and are executable