home / skills / plurigrid / asi / how-to-write-rulebooks

how-to-write-rulebooks skill

safe

This skill guides you to author, structure, and publish high-quality Rulebooks in Stakpak with a reusable, standardized workflow.

npx playbooks add skill plurigrid/asi --skill how-to-write-rulebooks

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.2 KB

---
name: how-to-write-rulebooks
description: |
  A practical, step-by-step guide that standardizes how to author, structure and publish rulebooks in Stakpak. It covers metadata creation, goal articulation, workflow design, reference inclusion and best-practice guidelines.
license: MIT
tags:
  - rulebook-creation
  - knowledge-management
  - devops-automation
  - best-practice
  - stakpak-cli
metadata:
  author: Stakpak <[email protected]>
  version: "1.0.2"
---

## Goals

* Make it easy for anyone to write and share Rulebooks

* Standardize how operational knowledge is captured and reused

* Enable Stakpak to help users create high quality Rulebooks

## Workflow

When generating a new Rule Book, always follow this process:

### Step 1: Start with Metadata

**URI:** <category>/<name>\
**Description:** The description will help Stakpak know what this Rulebook is about, its scope, and when to use it, keep this short and to the point\
**Tags:** create at least three tags to help Stakpak find this Rulebook in the future with keyword search

### Step 2: Write the Goals

Explain the outcome the user will achieve by following this Rule Book. The goal should be written as a clear, outcome oriented sentence:

**Bad:** "This Rule Book is about Kubernetes."

**Good:** "This Rule Book helps you deploy and scale applications on Kubernetes with production grade configuration."

### Step 3: Write the Workflow

Provide a numbered, step by step guide that explains how to accomplish the goal, maximize re-usability by avoiding hard coded values.

Each step should include:

**Action:** Imperative instruction (e.g., "Install the CLI tool").

**Reasoning:** Why this step is required (optional but recommended).

**Examples:** Code samples, commands, or configuration snippets where applicable.

Guidelines:

* Use short, direct sentences

* Keep steps atomic (one action per step)

* Include necessary context but avoid unnecessary details and hard-coded literals

### Step 4: Add References

Conclude the Rule Book with a "References" section.\
This section should contain:

* Links to official documentation or standards

* Related Rulebooks

* External resources for deeper learning

### Best Practices for Writing a Rule Book

* Use a clear structure, and concise text

* Only include new information and insights learned throughout the session, for example good patterns you see, and information you learn by doing web research. This information should complement LLM agents, so repeating knowledge the agent already processes is redundant and reduces the quality of this Rulebook

* You can add a prerequisites with conditions and initial requirements in the description (e.g. only run if there is Terraform code)

* You can ask the agent in the Rulebook to follow certain standards and guidelines

  * Principle of least privilege

  * OWASP Guidelines (with reference to which guidelines exactly)

  * AWS Well Architected Framework

  * Or even your internal company guidelines found in other Rulebooks (with reference)

### Using the stakpak CLI to manage Rulebook

```
# Get rulebook(s) (URI is optional - if not provided, lists all rulebooks)
stakpak rb get [URI]

# Apply/create a rulebook from a markdown file
stakpak rb apply <FILE_PATH>

# Delete a rulebook
stakpak rb delete <URI>
```

Overview

This skill is a practical, step-by-step guide for authoring, structuring, and publishing Rulebooks in Stakpak. It standardizes metadata, goal statements, workflows, references, and publishing steps so contributors produce consistent, reusable operational knowledge. The guide emphasizes concise, outcome-oriented writing and reuse-friendly workflows.

How this skill works

The skill inspects and enforces a four-step Rulebook creation process: metadata, goals, workflow, and references. It checks for required metadata fields (URI, description, tags), validates that the goal is outcome-oriented, and ensures the workflow is a numbered, atomic set of steps with actions, reasoning, and examples where applicable. Finally, it requires a references section and gives CLI commands for managing the Rulebook.

When to use it

Creating a new Rulebook for Stakpak to share operational knowledge
Standardizing existing Rulebooks to a reusable, searchable format
Teaching contributors how to write actionable, outcome-focused Rulebooks
Auditing Rulebooks to ensure metadata and references are present
Preparing Rulebooks for automated ingestion or CLI publishing

Best practices

Start with concise metadata: URI, short description, and at least three tags
Write a single, outcome-oriented goal sentence that defines success
Design the workflow as numbered, atomic steps; include Action, Reasoning, and Examples
Avoid hard-coded values; prefer placeholders and variables for reuse
Add a References section with docs, related Rulebooks, and external resources
Follow principle of least privilege and relevant standards (OWASP, AWS Well-Architected) and reference them explicitly

Example use cases

Author a Rulebook to deploy and scale an application with production-grade configuration
Standardize a team’s incident response steps so they are repeatable and auditable
Create a Rulebook that instructs agents to validate Terraform conditions before execution
Publish a library of operational patterns with metadata for fast discovery
Convert ad hoc runbooks into reusable Rulebooks with clear goals and examples

FAQ

What minimum metadata is required to publish a Rulebook?

Provide a URI in the form category/name, a short description explaining scope and when to use it, and at least three tags for discoverability.

How should workflow steps be written?

Use numbered, atomic steps. Each step should include an imperative Action, optional Reasoning, and Examples or command snippets when helpful. Avoid hard-coded literals and keep sentences short.