writing-skills

name

writing-skills

description

Create, edit, and verify golem-powers skills following the standard SKILL.md structure. Provides templates for skill frontmatter, workflow files, adapter files, and eval fixtures. Includes validation checks for description length, trigger word coverage, and structural completeness. Use when creating a new skill from scratch, editing an existing skill's structure or content, adding workflows or adapters to a skill, or verifying a skill meets quality standards before deployment. Triggers on 'create skill', 'write skill', 'new skill', 'skill template', 'edit skill', 'skill structure'. NOT for: invoking existing skills (call them directly), superpowers skills (different structure and location), or skill-creator agent workflows. Use when this capability is needed.

Writing Golem-Powers Skills

Meta-skill for creating executable skills. Skills are tools that Claude can invoke and automatically execute.

Skill Structure

Every golem-powers skill MUST have this structure:

skills/golem-powers/<skill-name>/
├── SKILL.md              # REQUIRED: Frontmatter + documentation
├── CLAUDE.md             # OPTIONAL: Environment requirements, complex setup
├── scripts/              # REQUIRED: Executable files
│   ├── default.sh        # Pattern A: Bash script
│   └── run.sh            # Pattern B: Wrapper for TypeScript
├── src/                  # OPTIONAL: TypeScript source (Pattern B)
│   └── index.ts
├── package.json          # OPTIONAL: Required if using TypeScript
├── bun.lock              # OPTIONAL: Required if using TypeScript
└── workflows/            # OPTIONAL: Multi-step procedures
    ├── create.md
    └── verify.md

SKILL.md Frontmatter (REQUIRED)

---
name: <skill-name>
description: <when to use this skill - shown in skill discovery>
execute: scripts/default.sh  # Path to script Claude runs on invocation
---

The execute: field is what makes a skill executable. When Claude loads a skill with execute: frontmatter, it MUST run that script IMMEDIATELY via Bash before any other action.

---

Dual Execution Patterns

Pattern A: Bash Script

Best for: Simple CLI wrappers, no dependencies, quick operations.

Frontmatter:

execute: scripts/review.sh

Structure:

skill-name/
├── SKILL.md
└── scripts/
    └── review.sh    # chmod +x

Script conventions:

• Scripts output Markdown for Claude to parse
• Use set -euo pipefail for safety
• Exit 0 on success, non-zero on failure
• Print errors to stderr, results to stdout
• MUST use BASH_SOURCE for path detection (see Path Standard below)

Example script:

#!/usr/bin/env bash
set -euo pipefail

# REQUIRED: Self-detect script location (works from any cwd)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"

echo "## Review Results"
echo ""
some-cli-tool review --format markdown

---

Pattern B: TypeScript/Bun

Best for: Complex logic, API calls, type safety, structured data processing.

Frontmatter:

execute: scripts/run.sh --action=default

Structure:

skill-name/
├── SKILL.md
├── scripts/
│   └── run.sh       # Wrapper that calls bun
├── src/
│   └── index.ts     # Main TypeScript file
├── package.json
└── bun.lock

The wrapper script (scripts/run.sh):

#!/usr/bin/env bash
set -euo pipefail

# REQUIRED: Self-detect script location (works from any cwd)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"

cd "$SKILL_DIR"
bun run src/index.ts "$@"

TypeScript requirements:

• Use Bun runtime (fast, TypeScript-native)
• Accept CLI arguments via process.argv
• Output Markdown or JSON to stdout
• Handle errors gracefully with exit codes

---

CLI Pattern (for TypeScript skills)

Use flags to support multiple operations in one skill:

--action Flag

execute: scripts/run.sh --action=default

Available actions defined in your TypeScript:

const action = process.argv.find(a => a.startsWith('--action='))?.split('=')[1] || 'default';

switch (action) {
  case 'default':
    // Main skill behavior
    break;
  case 'verify':
    // Verification mode
    break;
  case 'list':
    // List mode
    break;
}

--env Flag

For environment selection:

scripts/run.sh --action=deploy --env=prod

const env = process.argv.find(a => a.startsWith('--env='))?.split('=')[1] || 'dev';

---

Execution Rule

CRITICAL: When loading a golem-powers skill with execute: frontmatter, the agent MUST run that script IMMEDIATELY before any other action.

This means:

1. Agent loads the skill SKILL.md
2. Agent sees execute: scripts/foo.sh
3. Agent IMMEDIATELY runs the script via shell — path depends on CLI:
   • Claude Code: bash ~/.claude/commands/<skill>/scripts/foo.sh
   • Codex / Cursor / Gemini: bash ~/.agents/skills/<skill>/scripts/foo.sh
4. Agent reads the output
5. Only THEN does the agent proceed with other actions

This ensures skills are executable tools, not just documentation.

---

Quick Actions

What you want	Workflow
Create a new skill	workflows/create.md
Audit skill structure	workflows/audit.md

---

Template Generator

Use the included script to scaffold new skills:

# Claude Code
bash ~/.claude/commands/writing-skills/scripts/create-skill.sh \
  --name=my-skill \
  --type=bash

# Codex / Cursor / Gemini
bash ~/.agents/skills/writing-skills/scripts/create-skill.sh \
  --name=my-skill \
  --type=bash

Options:

• --name=<skill-name> (required): Name for the new skill
• --type=bash|typescript (required): Execution pattern
• --output=<path> (optional): Output directory (default: ./skills/golem-powers/)

This creates:

• Pattern A (bash): SKILL.md, scripts/default.sh
• Pattern B (typescript): SKILL.md, scripts/run.sh, src/index.ts, package.json

---

Examples

See working examples in this repo:

• skills/golem-powers/example-bash/ - Simple bash skill
• skills/golem-powers/example-typescript/ - TypeScript/Bun skill

---

Safety Rules

1. Always chmod +x - All scripts must be executable
2. Test before commit - Run shellcheck on all .sh files
3. Output Markdown - Scripts should return Markdown Claude can parse
4. Exit codes matter - 0 = success, non-zero = failure
5. Use BASH_SOURCE pattern - All scripts MUST self-detect their location

Path Standard (CRITICAL)

All skill scripts MUST use this pattern for portability:

#!/usr/bin/env bash
set -euo pipefail

# REQUIRED: Self-detect script location (works from any cwd)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"

# Now use absolute paths relative to skill
source "$SKILL_DIR/config.sh"  # If needed

For project detection (when script needs prd-json/, package.json, etc.):

# Walk up from cwd to find project root
find_project_root() {
    local dir="$PWD"
    while [[ ! -d "$dir/prd-json" && "$dir" != "/" ]]; do
        dir="$(dirname "$dir")"
    done
    if [[ -d "$dir/prd-json" ]]; then
        echo "$dir"
    else
        echo ""
    fi
}

PROJECT_ROOT="$(find_project_root)"
if [[ -z "$PROJECT_ROOT" ]]; then
    echo "Error: Cannot find prd-json/ directory" >&2
    exit 1
fi

Why this matters:

• Skills are symlinked into a CLI-specific directory, but agents run from project directories:
  • Claude Code: ~/.claude/commands/<skill>/
  • Codex / Cursor / Gemini: ~/.agents/skills/<skill>/
• Relative paths like ./scripts/foo.sh fail when cwd != skill directory
• BASH_SOURCE provides reliable self-location regardless of invocation context or CLI

See contexts/skill-authoring.md for full details.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.