GolemsGolems
Skills LibraryView on GitHub
Quality

/writing-skills

Use when creating new golem-powers skills, editing existing skills, or verifying skills work. Covers create skill, write skill, skill template, skill structure. NOT for: using existing skills (invoke them directly), superpowers skills (different structure).

$ golems-cli skills install writing-skills
Good
100% best pass rate
10 assertions
3 evals
2 workflows

Updated 2 weeks ago

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';

Workflows

/writing-skills:audit/writing-skills:create