skillet AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Skillet is a CLI tool written in Go that executes Claude Agent Skills (from agentskills.io) and commands as shell scripts with formatted output. It parses SKILL.md and command.md files, extracts frontmatter configuration (allowed-tools, model, etc.), interpolates variables like {baseDir}, and invokes the Claude CLI with appropriate permissions in headless mode. Output is formatted using Charm libraries (glamour, lipgloss) for clean terminal rendering.

Always test, format and lint code before finishing

go test ./...
go fmt ./...
golangci-lint run

Architecture

Core Components

main.go (cmd/skillet/main.go): Entry point that orchestrates the execution flow:

• Parses CLI flags using custom flag separation logic to support flags anywhere in args
• Resolves skill/command name → file path via resolver package
• Builds executor config from merged CLI flags + frontmatter
• Runs executor and formatter concurrently using pipes
• Handles signals and context cancellation

parser (internal/parser/): Parses SKILL.md files with YAML frontmatter

• Extracts frontmatter (name, description, allowed-tools, model, etc.)
• Interpolates {baseDir} variables in content
• Validates skill structure and constraints (name format, field lengths)

command (internal/command/): Parses command .md files (similar to skills but simpler)

• Derives command name from filename
• Supports optional frontmatter (description can be auto-extracted from content)
• Handles variable interpolation like skills

executor (internal/executor/): Builds and runs claude CLI commands

• Constructs args from resolved config (model, allowed-tools, system-prompt, etc.)
• Executes in headless mode with -p --verbose --output-format stream-json
• Provides dry-run mode to show command without executing

formatter (internal/formatter/): Processes claude's stream-json output into readable markdown