Use when executing, coordinating, planning, or reviewing readme builder agent workflows, cognitive loops, and architecture standards.
Pro shows the line behind each finding and how to fix it
Scanned 9/29/2026
Skills Directorynpx -y skills add Harmitx7/tribunal-kit --skill readme-builder --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Readme Builder?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/harmitx7-readme-builder)More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.
---
name: readme-builder
description: "Use when executing, coordinating, planning, or reviewing readme builder agent workflows, cognitive loops, and architecture standards."
version: 6.0.0
last-updated: 2026-09-29
skills:
- documentation-templates
- geo-fundamentals
- github-operations
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
- .agent/scripts/lint_runner.js
- .agent/scripts/verify_all.js
---
# README Builder Skill
## Mandatory Pre-Flight Context Inspection
Before reading, generating, or refactoring code in the `readme-builder` domain, inspect these 5 critical parameters:
1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
## Activation Boundaries
- **Activate when:** Use when executing, coordinating, planning, or reviewing readme builder agent workflows, cognitive loops, and architecture standards.
- **DO NOT activate when:** The task falls outside the `readme-builder` domain or is managed by a different dedicated specialist agent.
## 🔁 Multi-Pass Execution Protocol
| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
---
## 🛠️ Technical Architecture & Reference Recipes
## Hallucination Traps (Read First)
- ❌ Starting a README with the project name as the only heading -> ✅ Lead with what the project DOES, not just what it IS
- ❌ Skipping installation and quick-start sections -> ✅ Users need to run the project in under 60 seconds or they leave
- ❌ Using screenshots without alt text -> ✅ All images need descriptive alt text for accessibility and broken image fallback
---
## Ground Rules
1. **Always scan the project first** — read `package.json`, `pyproject.toml`, source files before writing a single line
2. **No placeholder content** — every section must have real, specific information
3. **Lead with value** — the first 3 lines must communicate what the project does and who it's for
4. **Runnable examples** — every code block must be copy-paste ready and tested against the actual project
---
## Discovery Phase (Mandatory Before Writing)
Before generating any README content, answer these questions by scanning the project:
```
1. What does this project do? (single sentence)
2. Who is the target user? (developer / end-user / enterprise)
3. What problem does it solve?
4. What are the installation prerequisites?
5. What is the primary command or API entry point?
6. Does it have a license file?
7. Are there screenshots, demos, or GIFs available?
8. Is there a CONTRIBUTING.md or CODE_OF_CONDUCT.md?
9. What CI/CD badges are relevant? (GitHub Actions, npm, PyPI, etc.)
10. What is the current version?
```
---
## README Structure Template
````markdown
# [Project Name]
[One-line tagline: what it does and for whom]
[](LICENSE)
[](https://www.npmjs.com/package/package-name)
[](https://github.com/user/repo/actions)
[Optional: Screenshot or GIF Demo]
---
## ✨ Features
- **Feature 1** — specific, concrete description
- **Feature 2** — specific, concrete description
- **Feature 3** — specific, concrete description
---
## 📋 Prerequisites
- Node.js 18+ / Python 3.11+ / etc.
- [Any specific tool or account required]
---
## 🚀 Installation
```bash
# npm
npm install package-name
# or yarn
yarn add package-name
# or global CLI install
npm install -g package-name
```
````
---
## 💻 Usage
### Basic Example
```bash
# One-liner that shows the most common use case
package-name --flag value
```
### Advanced Example
```bash
# More complex real-world usage
package-name init --config ./config.json --output ./dist
```
---
## ⚙️ Configuration
| Option | Type | Default | Description |
| --------- | --------- | ----------- | ---------------- |
| `option1` | `string` | `"default"` | What it controls |
| `option2` | `boolean` | `false` | What it controls |
---
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feat/your-feature`
3. Commit changes: `git commit -m "feat: add your feature"`
4. Push to branch: `git push origin feat/your-feature`
5. Open a Pull Request
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
---
## 📄 License
[MIT](LICENSE) © [Author Name]
````
---
## Badge Reference
### Common Badges (GitHub-hosted project)
```markdown
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/js/PACKAGE-NAME)
[](https://www.npmjs.com/package/PACKAGE-NAME)
[](https://github.com/USER/REPO)
[](https://github.com/USER/REPO/issues)
[](https://github.com/USER/REPO/actions)
[](https://codecov.io/gh/USER/REPO)
````
---
## Section Writing Guidelines
### Hero Section (Lines 1–5)
- Project name as `# H1` — only one per README
- Tagline in a `> blockquote` — punchy, one sentence
- Badges immediately after — visual trust signals
### Features Section
- Use emoji bullets for scannability
- Each bullet = one concrete capability, not a vague claim
- ❌ "Powerful and flexible" → ✅ "Processes 10k records/sec with zero config"
### Installation Section
- Always show the most direct path first (e.g., `npm install`)
- Show alternatives (yarn, pnpm, brew) as secondary options
- If there are post-install steps (env vars, migrations), list them explicitly
### Usage Section
- Start with the simplest 1-line example
- Progress to realistic examples with real flag names
- If it's a library, show import + function call pattern
### Configuration Table
- Every environment variable or config key goes here
- Include: name, type, default, description
- Mark required fields with `*` in the Description column
---
## Project-Type Specific Additions
### CLI Tools
Add a dedicated `## Commands` section:
```markdown
## Commands
| Command | Description |
| ------------- | -------------------------- |
| `tool init` | Initialize a new project |
| `tool build` | Compile and bundle |
| `tool deploy` | Deploy to production |
| `tool --help` | Show all available options |
```
### Libraries / SDKs
Add a `## API Reference` section with function signatures:
```markdown
## API Reference
### `functionName(param1, param2)`
Returns: `ReturnType`
| Parameter | Type | Description |
| --------- | --------- | --------------- |
| `param1` | `string` | Description |
| `param2` | `options` | Optional config |
```
### Monorepos
Add a `## Packages` table:
```markdown
## Packages
| Package | Version | Description |
| ---------------------------- | -------------------------------------------------------------------------- | ------------- |
| [`@org/core`](packages/core) | [](https://npm.im/@org/core) | Core engine |
| [`@org/cli`](packages/cli) | [](https://npm.im/@org/cli) | CLI interface |
```
---
## Output Format
When this skill generates or reviews a README, structure your response as:
```
━━━ README Builder Report ━━━━━━━━━━━━━━━━━━━━━━━━━
Skill: readme-builder
Project: [project name / type detected]
Sections: [list of sections generated]
─────────────────────────────────────────────────────
✅ Included: [sections that are complete]
⚠️ Missing: [sections that should be added]
❌ Blocked: [issues preventing completion]
─────────────────────────────────────────────────────
VBC status: PENDING → VERIFIED
Evidence: [file written at path / content reviewed]
```
## 🚨 Edge-Case & Failure Mode Matrix
| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
## 🏛️ Tribunal Verification & Guardrails
**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
**Slash Command:** `/review` or `/tribunal-full`
### 🔬 Evidence Standard (Tri-State Verification)
Every finding, audit statement, or completion claim must classify its factual certainty:
- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.
### ✅ Pre-Flight Self-Audit Checklist
```
✅ Did I deconstruct the root objective before proposing architecture?
✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
✅ Did I avoid over-engineering and select the simplest effective pattern?
✅ Did I verify assumptions with concrete file reads instead of speculation?
✅ Did I establish measurable verification criteria before completion?
```
### 🛑 Verification-Before-Completion (VBC) Protocol
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
