Architecture Overview

The Pack

singularskills is one pack of skills in a flat layout. Domains are not packaging units: they survive as the first segment of every skill name (design-empathize, project-management-sprint-planning) and as the grouping in these docs.

skills/<name>/          # One folder per skill: SKILL.md, plus scripts/ (gates) and references/
workflows/<name>.yml    # One file per workflow: ordered phases, artifacts, requires, member skills
references/             # Shared reference material, copied into each skill that uses it
adapters/               # Thin, generated per-agent extras (Claude command wrappers and gate hook, Gemini commands)
evals/<skill>/          # claude plugin eval cases

Skills are the unit every agent loads. Workflows order the skills into phases, and the workflow skill (the conductor) runs them one phase at a time with an approval at each boundary. References hold the templates and criteria a skill reads, such as the WCAG criteria. A pack-tools script copies each one into the references/ folder of every skill that needs it, so an installed skill is self-contained. Adapters are generated from skills/ and workflows/ and checked in CI. They add only what a specific agent needs, and none of them duplicates skill text.

The Skill System

Each skill is a Markdown file (SKILL.md) with YAML frontmatter and structured instructions. When you run a command like /design-empathize button, or describe the task in plain words, your agent loads the matching skill and follows its instructions.

Skills define:

• Description: what the skill does and when to use it (used for matching)
• Prerequisites: what artifacts must exist before running, and the gate script that checks them
• Process: step-by-step instructions for the agent to follow
• Output: what artifact to write and where, with its frontmatter and closing sections

Gates and the Run Log

A skill whose phase requires earlier artifacts ships scripts/gate.sh, a POSIX shell script with no dependencies. It exits 1 and names any required artifact that is missing. The skill runs it first and stops on a refusal; --skip-checks bypasses it, but only after the skill appends a skipped event to the run log. In Claude Code, the plugin's PreToolUse gate hook runs the same check before any write into .singularskills/, and honours a bypass only when that skipped event is in the log.

The run log, .singularskills/log.jsonl, is append-only. Skills and the conductor add one JSON line per event: run started, phase approved, gate skipped and so on. The Workflows page has the exact shapes of the log and the artifacts.

The design skills' Figma steps call a Figma MCP server that you configure in your agent; the pack itself ships no MCP server and makes no network calls (see the design workflow page).

Evals (on demand)

Each domain's most-used first skill, and the conductor, has a claude plugin eval case under evals/<skill>/. bun run evals runs every case with and without the pack and reports whether the skill fired and how much its output improves on the baseline. Evals spend Claude credits, so they run on demand rather than in CI; see How Skills Are Tested.

Monorepo Structure

singularskills/
  skills/ workflows/ references/ adapters/ evals/   # The pack
  packages/
    skill-validator/    # Validates SKILL.md format
    pack-tools/         # Pack consistency checks and generators (gates, references, adapters)
  apps/
    docs/               # This documentation site

Built with Turborepo + Bun. The packages are internal tools; the pack is the user-facing product.