playbooks

home / skills / documenso / documenso / create-scratch

create-scratch skill

/.opencode/skill/create-scratch

This skill creates new scratch files in .agents/scratches with a unique three-word ID, frontmatter, and formatted title to organize ideas.

npx playbooks add skill documenso/documenso --skill create-scratch

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

Files (1)
SKILL.md
1.2 KB
---
name: create-scratch
description: Create a new scratch file in .agents/scratches/ with a unique three-word ID, frontmatter, and formatted title
license: MIT
compatibility: opencode
metadata:
  audience: agents
  workflow: exploration
---

## What I do

I help you create new scratch files in the `.agents/scratches/` directory. Each scratch file gets:

- A unique three-word identifier (e.g., `calm-teal-cloud`)
- Frontmatter with the current date and formatted title
- Content you provide

## How to use

Run the script with a slug and content:

```bash
npx tsx scripts/create-scratch.ts "note-name" "Scratch content here"
```

Or use heredoc for multi-line content:

```bash
npx tsx scripts/create-scratch.ts "note-name" << HEREDOC
Multi-line
scratch content
goes here
HEREDOC
```

## File format

Files are created as: `{three-word-id}-{slug}.md`

Example: `calm-teal-cloud-note-name.md`

The file includes frontmatter:

```markdown
---
date: 2026-01-13
title: Note Name
---

Your content here
```

## When to use me

Use this skill when you need to create a temporary note, exploration document, or scratch pad for ideas. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.

Overview

This skill creates a new scratch file inside .agents/scratches/ using a guaranteed-unique three-word identifier, frontmatter, and a cleanly formatted title. It produces Markdown files named {three-word-id}-{slug}.md and injects the current date and your provided content. The result is a collision-free, organized scratch note ready for use in documentation workflows or quick experiments.

How this skill works

You invoke the script with a slug and content (single-line or heredoc for multi-line). The tool generates a three-word ID (for example, calm-teal-cloud), formats the title from the slug, writes frontmatter with the current date and title, and saves the file to .agents/scratches/. The final filename is {three-word-id}-{slug}.md and includes your content after the frontmatter.

When to use it

  • Quickly capture a temporary note, idea, or experiment without worrying about filename collisions.
  • Create exploratory documentation or a scratch pad when iterating on features or designs.
  • Add a timestamped, searchable Markdown note to a repository-based workflow.
  • Store short-lived content that may later be promoted to a formal document.
  • Generate reproducible, uniquely identified notes for team handoffs or reviews.

Best practices

  • Use descriptive slugs (kebab-case) so titles are readable and searchable when the ID is appended.
  • Prefer heredoc for multi-line or formatted content to preserve line breaks and structure.
  • Treat scratches as ephemeral: move or refactor important notes into permanent docs or pages.
  • Keep the content focused and concise; frontmatter already captures date and title metadata.
  • Commit .agents/scratches/ selectively based on your repository policy for ephemeral files.

Example use cases

  • Capture meeting notes or action items during a quick sync without interrupting your repo structure.
  • Create a one-off test plan or troubleshooting log while debugging a digital-signature workflow.
  • Draft an integration note for Next.js or Prisma changes before formalizing in docs.
  • Record a reproducible bug report or short walkthrough that references PDF signing behavior.
  • Save algorithmic experiments or sample code for later review without naming conflicts.

FAQ

How do I pass multi-line content?

Use a heredoc with the script to feed multi-line content, which preserves formatting and line breaks.

What does the three-word ID prevent?

The three-word ID ensures unique filenames to avoid collisions when multiple scratches share the same slug.