Skip to content

Skills

Skills are RaiSE's process-as-code. Each skill is a structured workflow — a SKILL.md file — that guides both you and your AI partner through a specific engineering activity. Think of them as runbooks that your AI can follow, not just read.

What a Skill Looks Like

A skill is a markdown file in .claude/skills/<name>/SKILL.md with:

  • Purpose — what this skill does and when to use it
  • Steps — ordered sequence with verification gates at each step
  • Mastery levels — Shu (follow exactly), Ha (adapt), Ri (create your own)
  • Inputs and outputs — what it needs, what it produces

When you invoke a skill (e.g., /rai-story-plan), your AI loads the SKILL.md and follows its steps — checking prerequisites, executing each step, verifying results, and producing documented output.

The Story Lifecycle

The most important skill chain is the story lifecycle — the sequence that takes a feature from idea to merged code:

/rai-story-start    → Create branch and scope commit
      ↓
/rai-story-design   → Design the specification
      ↓
/story-plan     → Decompose into atomic tasks
      ↓
/rai-story-implement → Execute tasks with TDD
      ↓
/rai-story-review   → Retrospective and learnings
      ↓
/rai-story-close    → Verify, merge, cleanup

Each step produces an artifact (scope.md, design.md, plan.md, progress.md, retrospective.md) and has verification gates that must pass before proceeding. This isn't bureaucracy — it's how you ensure consistency and traceability across sessions.

Skill Lifecycles

Skills are organized by the work lifecycle they belong to:

Lifecycle Skills When
Session /rai-session-start, /rai-session-close Every working session
Story /rai-story-start through /rai-story-close For each feature
Epic /rai-epic-start through /rai-epic-close For multi-story bodies of work
Discovery /rai-discover When analyzing a codebase

Lean Principles in Skills

Every design skill (story and epic) enforces lean engineering principles:

  • Gemba walk — before designing anything, read the actual code. Understand current state, search for existing implementations, check established patterns. Design without reading code is guessing.
  • KISS — is this the simplest approach that works?
  • DRY — does this duplicate logic that exists elsewhere?
  • YAGNI — are you building for a real requirement or a hypothetical one?
  • MVP — what's the smallest version that delivers value? Build that, not more.

Review skills (architecture review, quality review) close the loop — they verify that lean principles were actually followed in implementation, not just stated in design.

Skills and Pipelines

Skills can be invoked manually (/rai-story-design) or orchestrated by a pipeline. A pipeline sequences skills into an automated lifecycle, adding:

  • Context injection — knowledge graph patterns and modules loaded automatically
  • Artifact validation — required outputs verified before proceeding
  • HITL gates — human checkpoints at critical decision points
  • Delegation levels — controls how much autonomy the pipeline has (ShuHaRi)

The same SKILL.md works in both modes. Pipelines don't change skills — they automate the sequencing.

Skills vs. CLI

This distinction matters:

  • Skills guide the process — they tell you and your AI what to do, in what order, with what verification
  • CLI handles the data — it reads, writes, builds, and queries deterministically

A skill like /rai-story-plan tells the AI to decompose a story into tasks. The CLI command rai signal emit-work records the event. The skill orchestrates; the CLI executes.

Mastery Levels (ShuHaRi)

Every skill supports three mastery levels, borrowed from martial arts:

  • Shu (守) — Follow the form exactly. For new practitioners or new skill types.
  • Ha (破) — Adapt the form. Skip optional steps, adjust to context. For experienced practitioners.
  • Ri (離) — Transcend the form. Create custom patterns. For experts who understand the principles deeply enough to improvise.

Your experience level is tracked in your developer profile and included in the context bundle. At Shu level, skills provide detailed explanations. At Ri level, they show essentials only.

Verification Gates

Every skill step has a verification criterion — a concrete check that the step was completed correctly. If verification fails, the skill stops (Jidoka principle: stop on defects, don't accumulate errors).

Examples of verification gates: - "Epic branch exists" before creating a story branch - "Plan exists" before starting implementation - "Tests pass" before committing - "Retrospective complete" before merging

Managing Skills

# List all skills
rai skill list

# Validate skill structure
rai skill validate

# Create a new skill from template
rai skill scaffold my-new-skill --lifecycle story

# Check naming conventions
rai skill check-name my-new-skill

See the [CLI Reference](../cli/index.md/ for full details.