Skills Guide

Scaffold and validate RFCs

VerifiedSafe

Scaffold and validate ArenaQuest RFCs against a house standard: numbered files, metadata headers, canonical sections, and README index rows.

Download and use
Sby Skills Guide Bot
DocumentationIntermediate
9/11/2026
Claude Code
#rfc#documentation#templates#validation#node-scripts

Recommended for

Claude CodeAuto documentation

Automated summary

Scaffolds and validates ArenaQuest repository RFCs against the house standard using two dependency-free Node scripts.

Strengths

  • Automatically creates the next numbered RFC file (NNNN-kebab-title.md) and appends its index row to the README
  • The check-rfc.mjs validator separates hard violations (exit 1) from missing recommended sections (advisory warning, exit 0)
  • Backed by a template.md that explains what prose belongs in each canonical section
  • Straightforward CLI flags for status, date, author and target directory

Limitations

  • Tightly bound to the ArenaQuest layout (docs/product/RFCs) and its naming conventions
  • The standard is advisory only for legacy RFCs (0001 in Portuguese, 0003 with the date embedded in the status line)
  • The .claude/skills symlink and the WSL bridge can raise ENOTDIR errors or swallow exit codes
When to use it

Use it whenever you need to draft, create or check an RFC under docs/product/RFCs in this repository.

When not to use it

Skip it for proposals outside the ArenaQuest repo or in projects that don't follow this RFC format.

Security analysis

Safe
Quality score92/100

The skill instructs running two local Node scripts that scaffold and validate RFC documents using only the standard library. There is no network access, no destructive commands, no exfiltration, and no obfuscation. The scripts operate on repository files for a legitimate documentation workflow.

No concerns found

How this analysis is made

Examples

Scaffold a new RFC
Create a new RFC titled 'Enrollment exclusions and visibility', author raphaelsilva, status Draft, then show me the created file path.
Validate one RFC
Check docs/product/RFCs/0005-enrollment-exclusions-and-visibility.md against the RFC standard and tell me which sections are missing.
Validate all RFCs
Run the RFC validation over every file in docs/product/RFCs and list the hard violations that would fail CI.

name: write-rfc description: Scaffold and validate ArenaQuest RFCs against the house standard so every proposal in docs/product/RFCs follows the same structure (numbered file, metadata header, canonical sections, README index row). Triggers: write rfc, create rfc, new rfc, draft rfc, scaffold rfc, rfc template, rfc standard, validate rfc, check rfc

ArenaQuest keeps formal proposals in docs/product/RFCs/ as NNNN-<kebab-title>.md, indexed by docs/product/RFCs/README.md. This skill enforces that standard with two dependency-free Node scripts:

  • new-rfc.mjs — scaffolds the next-numbered RFC from template.md and appends its index row to the README.
  • check-rfc.mjs — validates one or all RFCs against the standard; non-zero exit on a hard violation, so it drops into a pre-commit hook or CI.

Paths below are relative to the repo root (docs/product/RFCs, the scripts under .claude/skills/write-rfc/). Run them from the repo root.

The .claude/skills/ directory is a symlink to .agents/skills/. It resolves fine for the Node runtime (Linux). The Windows \\wsl.localhost bridge can't traverse the symlink — if a tool errors with ENOTDIR / Input/output error on .claude/skills/..., use the real path .agents/skills/write-rfc/... instead. Both point at the same files.

The standard

Every RFC has, in this order:

  1. Filename NNNN-<kebab-title>.md — 4-digit zero-padded, sequential.
  2. Title # RFC NNNN: <Title> — number matches the filename.
  3. Metadata block (bold fields): **Status:**, **Author:**, **Date:** (PT Autor: / Data: accepted), plus optional **Revised:** and an **Affected:** file list. Then a --- divider.
  4. Sections (##): Summary, Motivation, Goals & Non-Goals, Current State (omit if greenfield), Proposed Design, Alternatives Considered, Implementation Plan, Tradeoffs & Risks, Success Criteria, Open/Resolved Decisions, References. See template.md for the prose guidance per section.
  5. README index row in docs/product/RFCs/README.md.

Status lifecycle: Draft → Proposed → Approved → In Progress → Implemented/Done/Completed; or Rejected / Superseded.

Create a new RFC (agent path)

node .claude/skills/write-rfc/new-rfc.mjs "Title of the proposal" --author raphaelsilva

Prints the created path (e.g. docs/product/RFCs/0007-title-of-the-proposal.md) and adds the README index row. Options: --status (default Draft), --date YYYY-MM-DD (default today), --author (default git config user.name), --dir (default docs/product/RFCs). Then fill in each ## section — the template body explains what belongs in each.

Validate (agent path)

Check every RFC in the directory:

node .claude/skills/write-rfc/check-rfc.mjs

Check a single file (use this on the RFC you just wrote):

node .claude/skills/write-rfc/check-rfc.mjs docs/product/RFCs/0005-enrollment-exclusions-and-visibility.md

Output: ✓ clean, ⚠ recommended section missing (advisory — exit 0), ✗ hard violation (exit 1). ERROR = wrong filename, missing/mismatched # RFC NNNN title, missing Status/Author/Date metadata, or not linked from the README index. warn = a recommended ## section is absent (older RFCs predate the full skeleton, so these don't block).

Gotchas

  • .claude/skills is a symlink (→ .agents/skills). Native file tools reaching it over the Windows bridge throw Input/output error; run scripts through the WSL Node runtime, or edit files via .agents/skills/write-rfc/.
  • Exit codes are swallowed by the wsl.exe … bash -c '… ; echo $?' bridge — $? reads as 0 even when Node exited non-zero. To observe the real result use &&/|| evaluated inside WSL: node …/check-rfc.mjs && echo PASS || echo FAIL.
  • The standard is advisory for legacy RFCs. 0001 is Portuguese (Autor:/ Data: — accepted) and 0003 embeds its date inside the Status line, so check-rfc.mjs flags 0003 as ✗ missing Date. That is a real, known gap in an existing doc, not a script bug — don't "fix" the validator to hide it.
  • Numbering reads the directory, not the README. If a number was skipped or a draft file deleted, the next number follows the highest existing NNNN-*.md, not the index.

Files

  • .claude/skills/write-rfc/new-rfc.mjs — scaffolder (Node, stdlib only).
  • .claude/skills/write-rfc/check-rfc.mjs — validator (Node, stdlib only).
  • .claude/skills/write-rfc/template.md — the canonical section skeleton with per-section prose guidance; new-rfc.mjs fills its {{...}} placeholders.

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/scaffold-and-validate-rfcs-mtwgrt1e/download' --output '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md.part' && mv '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md.part' '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

After inspection, copy the complete folder into your project using one of the commands below, then open a new tool session. The command stops if a folder with the same name already exists: compare the files before replacing it.

Claude Code
test -f '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md' && test -s '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/write-rfc' && cp -R '.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e' '.claude/skills/write-rfc'

OpenSkills

OpenSkills must already be installed. The local install/read procedure is checked with OpenSkills 1.5.0, which requires Node.js ≥ 20.6.0. Catalog slugs are not resolved automatically.

Official OpenSkills installation
openskills install './.skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e'

openskills read 'scaffold-and-validate-rfcs-mtwgrt1e'

Reading should display the installed file content and its base directory. It does not run the skill or install its dependencies.

For an agent that reads AGENTS.md, then sync the index. This command changes AGENTS.md: review the diff before using it.

openskills sync

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/scaffold-and-validate-rfcs-mtwgrt1e/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills

Supabase Docs Authoring

Documentation

Write, edit, and review Supabase documentation content including guides, tutorials, reference docs, and partials. Follow style guides and MDX/TOML validation rules.

Claude CodeintermediateSafe 108,544
Skills Guide Bot

Create Architecture Decision Record

Documentation

Create a new Architecture Decision Record with sequential numbering, register it in the AgentDB graph, and link related ADRs.

Claude CodeintermediateSafe 69,659
Skills Guide Bot

Plan update with deep research

Documentation

Updates a plan document by launching parallel subagents to analyze a topic across all compiler passes, then consolidates findings into the plan doc.

Claude CodeadvancedSafe 248,015
Skills Guide Bot