AI Skills

Production-ready skills for Claude Code personas, Gorgon agent capabilities, and orchestrated workflows.

---

The Problem

Claude is powerful but generic. For specialized work you end up re-explaining context, missing domain best practices, and getting responses that don't match your workflow.

Skills fix this. Each skill transforms Claude into a specialized persona with defined behaviors, constraints, and output formats. Agent skills give Gorgon agents typed interfaces with risk levels and consensus requirements. Workflows coordinate them with the WHY/WHAT/HOW framework.

Quickstart

git clone https://github.com/AreteDriver/ai-skills.git
cd ai-skills

# Install a single skill
./tools/install.sh --persona code-reviewer

# Install a curated bundle
./tools/install.sh --bundle webapp-security

# Install everything
./tools/install.sh --all

# See what's available
./tools/install.sh --list

See it in action: Ask Claude to review a function with SQL injection — with the skill loaded, you get severity-ranked findings with line references and concrete fixes instead of vague suggestions.

Hello World: Create Your Own Skill in 60 Seconds

# 1. Create the skill directory
mkdir -p personas/domain/my-first-skill

# 2. Write the skill file
cat > personas/domain/my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: Responds to every question like a pirate captain
---

# My First Skill

## Role
You are a grizzled pirate captain who happens to be an expert software engineer.

## Core Behaviors
### Always
- Use nautical metaphors for technical concepts
- Address the user as "matey" or "first mate"
- End responses with "Fair winds and following seas"

### Never
- Break character
- Give incorrect technical advice despite the pirate persona
EOF

# 3. Install it
./tools/install.sh --persona my-first-skill

Now open Claude Code — your pirate engineer is ready. See the full Quickstart Guide for before/after comparisons across code review, architecture advice, and feature implementation workflows.

Architecture

┌─────────────────────────────────────────────────┐
│                   ai-skills                      │
├─────────────────┬───────────────┬───────────────┤
│    Personas     │    Agents     │   Workflows   │
│  (how Claude    │ (what Gorgon  │ (multi-step   │
│   behaves)      │  agents do)   │  execution)   │
├─────────────────┼───────────────┼───────────────┤
│ 51 skills       │ 16 skills     │ 3 workflows   │
│ SKILL.md only   │ SKILL.md +    │ SKILL.md +    │
│                 │ schema.yaml   │ schema.yaml   │
└─────────────────┴───────────────┴───────────────┘

Personas — User Behavior Skills

Engineering (7)

Skill	Purpose	Path
senior-software-engineer	Code review, architecture, mentoring	personas/engineering/
senior-software-analyst	Codebase auditing, system mapping	personas/engineering/
software-architect	System design, technical decisions	personas/engineering/
code-reviewer	Quality, security, best practices	personas/engineering/
code-builder	Production-ready implementation	personas/engineering/
testing-specialist	Test suite creation, TDD	personas/engineering/
documentation-writer	API docs, guides, READMEs	personas/engineering/

Data (4)

Skill	Purpose	Path
data-engineer	Pipelines, schemas, ETL	personas/data/
data-analyst	Statistical analysis, insights	personas/data/
data-visualizer	Charts, dashboards	personas/data/
report-generator	Executive summaries	personas/data/

DevOps (6)

Skill	Purpose	Path
backup	Backup strategy, disaster recovery	personas/devops/
monitor	Observability, alerting	personas/devops/
networking	Network config, troubleshooting	personas/devops/
systemd	Service management, unit files	personas/devops/
perf	Performance profiling	personas/devops/
process-management	Process lifecycle	personas/devops/

Claude Code Ecosystem (5)

Skill	Purpose	Path
hooks-designer	Hook design, lifecycle events	personas/claude-code/
plugin-builder	Plugin packaging	personas/claude-code/
mcp-server-builder	MCP server implementation	personas/claude-code/
session-memory-manager	Cross-session context	personas/claude-code/
cicd-pipeline	CI/CD for Claude Code	personas/claude-code/

Security (2)

Skill	Purpose	Path
security-auditor	OWASP audit, vulnerability assessment	personas/security/
accessibility-checker	WCAG 2.2 compliance	personas/security/

Domain-Specific (12)

Skill	Purpose	Path
mentor-linux	Linux cert prep (RHCSA, Linux+)	personas/domain/
eve-esi	EVE Online ESI API	personas/domain/
gamedev	Game dev (Bevy/Rust ECS)	personas/domain/
streamlit	Streamlit apps	personas/domain/
strategic-planner	Business strategy	personas/domain/
hauling-business-advisor	Junk hauling ops	personas/domain/
hauling-image-estimator	Visual load estimation	personas/domain/
hauling-job-scheduler	Job scheduling	personas/domain/
hauling-lead-qualifier	Lead qualification	personas/domain/
hauling-quote-generator	Quote generation	personas/domain/
tie-dye-business-coach	Tie-dye business coaching	personas/domain/
apple-dev-best-practices	Apple platform dev (Swift, SwiftUI)	personas/domain/

Web (11)

Skill	Purpose	Path
web-frontend-builder	React/Next.js/static frontend	personas/web/
web-backend-builder	API backends (FastAPI/Express)	personas/web/
web-designer	Visual design and design systems	personas/web/
web-deployer	Deployment and hosting	personas/web/
web-seo-optimizer	Search engine optimization	personas/web/
web-analytics	Traffic analytics and tracking	personas/web/
web-content-writer	Copy, blog posts, email	personas/web/
web-merchant	E-commerce and payments	personas/web/
web-cms-manager	WordPress, Ghost, headless CMS	personas/web/
web-performance	Speed and Core Web Vitals	personas/web/
web-security-hardener	Security headers and hardening	personas/web/

API & Integration (4)

Skill	Purpose	Path
api-tester	Contract, load, and regression testing	personas/api/
database-ops	Schema design, migrations, query optimization	personas/api/
webhook-designer	Webhook payload, retry, HMAC security	personas/api/
oauth-integrator	OAuth 2.0, PKCE, JWT, provider integration	personas/api/

Agents — Gorgon Capabilities

Agent skills define typed interfaces with inputs, outputs, risk levels, and Triumvirate consensus requirements.

Agent	Category	Risk	Consensus	Description
file-operations	system	medium	destructive ops	Safe filesystem operations
process-runner	system	medium	none	Subprocess execution with safety controls
web-search	browser	low	none	Rate-limited web search
web-scrape	browser	low	none	Ethical web scraping
email-compose	email	high	send ops	Draft-review-send email workflow
github-operations	integrations	medium	push ops	Git CLI and GitHub API
api-client	integrations	low	none	Authenticated HTTP API client
multi-agent-supervisor	orchestration	medium	adaptive	Gorgon supervisor with Triumvirate
agent-teams-orchestrator	orchestration	medium	none	Claude Code Agent Teams
technical-debt-auditor	analysis	low	none	Repo health scoring (5 sub-agents)
release-engineer	analysis	medium	publish	Last-mile shipping automation
entity-resolver	analysis	low	none	Fuzzy entity matching + dedup
context-mapper	analysis	low	none	Pre-execution project mapping
workflow-debugger	analysis	low	none	Gorgon failure diagnosis
document-forensics	analysis	low	none	Investigative document analysis
intent-author	analysis	low	none	Convergent intent authoring

Workflows — Multi-Step Execution

Workflows use the WHY/WHAT/HOW framework to ensure clear intent, scope, and execution strategy.

Workflow	Phase	Description
context-mapper	pre-execution	Codebase reconnaissance before agents write code
feature-implementation	full-lifecycle	Requirements → context → design → implement → test → PR
release-engineering	full-lifecycle	Preflight → review → changelog → version → tag → publish

WHY/WHAT/HOW Framework

Every workflow captures three dimensions:

• WHY — Intent: goal, motivation, success criteria, anti-goals
• WHAT — Scope: files in/out of scope, dependencies, data flows
• HOW — Plan: strategy, step sequence, patterns, risks, quality gates

See workflow-schema.yaml for the full schema definition.

Installation

Installer (recommended)

git clone https://github.com/AreteDriver/ai-skills.git
cd ai-skills

# Install a single persona
./tools/install.sh --persona code-reviewer

# Install a curated bundle (see below)
./tools/install.sh --bundle full-stack-dev

# Install everything
./tools/install.sh --all

# Symlink for development (edit in repo, changes appear in Claude Code)
./tools/install.sh --persona code-reviewer --symlink

# List all available skills and bundles
./tools/install.sh --list

# Remove installed skills
./tools/install.sh --uninstall

Manual Installation

# Copy persona skills
cp -r personas/engineering/code-reviewer ~/.claude/skills/

# Or symlink for development
ln -s $(pwd)/personas/engineering/code-reviewer ~/.claude/skills/code-reviewer

Project-Level Reference

# CLAUDE.md
See skills from: https://github.com/AreteDriver/ai-skills

Active skills:
- senior-software-engineer (always on for code tasks)
- mentor-linux (when studying)

Bundle Presets

Curated skill collections for common use cases. Install with ./tools/install.sh --bundle <name>.

Bundle	Skills	Use Case
webapp-security	code-reviewer, security-auditor, testing-specialist, accessibility-checker	Secure web app development
release-engineering	code-reviewer, cicd-pipeline	Shipping releases with confidence
data-pipeline	data-engineer, data-analyst, data-visualizer, report-generator	End-to-end data engineering
full-stack-dev	senior-software-engineer, code-reviewer, testing-specialist, software-architect, documentation-writer	Full engineering stack
claude-code-dev	hooks-designer, plugin-builder, mcp-server-builder, cicd-pipeline, session-memory-manager	Building Claude Code extensions
website-builder	web-frontend-builder, web-backend-builder, web-deployer, web-designer, web-seo-optimizer, web-analytics, web-performance, web-security-hardener	Full website lifecycle
website-ecommerce	web-frontend-builder, web-merchant, web-content-writer, web-seo-optimizer, web-deployer	E-commerce development
website-content	web-cms-manager, web-content-writer, web-seo-optimizer, web-analytics, web-designer	Content-driven sites
api-integration	api-tester, database-ops, webhook-designer, oauth-integrator	API development lifecycle

Bundle definitions live in bundles.yaml. Add your own by following the same format.

Validation

# Validate all skills (structure, frontmatter, registry consistency)
./tools/validate-skills.sh

# Check formatting (YAML syntax, markdown quality, shell syntax, line endings)
./tools/format-check.sh

# Verbose output
./tools/validate-skills.sh --verbose
./tools/format-check.sh --verbose

# Auto-fix issues (hook permissions, trailing whitespace, CRLF)
./tools/validate-skills.sh --fix
./tools/format-check.sh --fix

Both validators run in CI on every push and PR. See .github/workflows/validate-skills.yml.

Registry

registry.yaml is the central catalog of all skills. Gorgon's SkillLibrary loader uses it to discover, validate, and load skills at runtime.

# Query the registry
personas.engineering        # 7 skills
agents.system               # 2 skills (file-operations, process-runner)
workflows                   # 3 workflows (context-mapper, feature-implementation, release-engineering)

Skill Development

Creating a Persona

mkdir -p personas/<category>/<skill-name>
cp templates/skill-template.md personas/<category>/<skill-name>/SKILL.md
# Edit SKILL.md, add to registry.yaml
./tools/validate-skills.sh

Creating an Agent

mkdir -p agents/<category>/<skill-name>
# Create SKILL.md (behavior) + schema.yaml (typed interface)
# Add to registry.yaml
./tools/validate-skills.sh

Key Elements of a Skill

1. Frontmatter — name and description for tooling
2. Role definition — who the skill acts as
3. Core behaviors — what it always/never does
4. Trigger contexts — when to activate different modes
5. Output formats — how responses are structured
6. Constraints — hard limits on behavior

Agent skills additionally require: 7. schema.yaml — typed inputs, outputs, capabilities, risk levels, consensus requirements

Supporting Infrastructure

Directory	Purpose
bundles.yaml	Curated skill bundles for common use cases
examples/	Quickstart guide with before/after demos
hooks/	4 executable hook scripts (tdd-guard, no-force-push, protected-paths, tool-logger)
plugins/	Example quality-gate plugin bundling skills + hooks
playbooks/	Multi-step workflow guides (full-feature, debug-and-fix)
prompts/	7 legacy prompt templates
templates/	Skill and prompt templates
decisions/	ADR template
tools/	validate-skills.sh, format-check.sh, install.sh

Credits

Skills adapted from Gorgon multi-agent orchestration system and the original ClaudeSkills repository.

Author

ARETE — AI Enablement & Workflow Analyst

Community

Discord — Join the community

License

MIT