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):

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

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)

2. 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}"