Skip to content
Back to search

skills

SkillWorks with Claude CodeGitHub

A collection of skills for AI agents (Kiro, Cursor, Windsurf, Claude Code, and others). Each skill is a reusable module that teaches the agent to perform complex tasks with context, structure, and best practices.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/fabricioctelles/skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/fabricioctelles/skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fabricioctelles-skills/badge.svg)](/listings/fabricioctelles-skills)

HTML

<a href="/listings/fabricioctelles-skills"><img src="/api/listings/fabricioctelles-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You can install these skills using any compatible installer or manually. Below are the most popular options.

Via [Skills.sh](https://skills.sh/docs)

npx skills add https://github.com/fabricioctelles/skills

Or install a specific skill:

npx skills add https://github.com/fabricioctelles/skills -s startup-idea
npx skills add https://github.com/fabricioctelles/skills -s revenue-centric-design
npx skills add https://github.com/fabricioctelles/skills -s geo-optimization
npx skills add https://github.com/fabricioctelles/skills -s substack-expert
npx skills add https://github.com/fabricioctelles/skills -s humanizar
npx skills add https://github.com/fabricioctelles/skills -s human-ai
npx skills add https://github.com/fabricioctelles/skills -s pier-cloud
npx skills add https://github.com/fabricioctelles/skills -s coolify-operator
npx skills add https://github.com/fabricioctelles/skills -s astro-sites-manager
npx skills add https://github.com/fabricioctelles/skills -s security-specialist
npx skills add https://github.com/fabricioctelles/skills -s ultimate-design-system-master
npx skills add https://github.com/fabricioctelles/skills -s design-md-validator
npx skills add https://github.com/fabricioctelles/skills -s skill-evaluation
npx skills add https://github.com/fabricioctelles/skills -s slop-eval
npx skills add https://github.com/fabricioctelles/skills -s agent-plugin-eval
npx skills add https://github.com/fabricioctelles/skills -s agent-ready-cloudflare
npx skills add https://github.com/fabricioctelles/skills -s auth-md
npx skills add https://github.com/fabricioctelles/skills -s pstack-skill
npx skills add https://github.com/fabricioctelles/skills -s okf-open-knowledge-format
npx skills add https://github.com/fabricioctelles/skills -s ralph-loop-kiro-specs
npx skills add https://github.com/fabricioctelles/skills -s loop-architect
npx skills add https://github.com/fabricioctelles/skills -s resume-ats-beater

Via [SkillKit](https://github.com/rohitg00/skillkit)

A package manager for skills with cross-agent translation. Runs with zero install:

npx skillkit add fabricioctelles/skills

Or install the CLI globally:

npm install -g skillkit                    # full
npm install -g skillkit --omit=optional    # slim, ~75% smaller, no native addons

skillkit install fabricioctelles/skills

Target specific agents (46 supported, including Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Copilot, OpenCode, Kiro):

skillkit install fabricioctelles/skills --agent claude-code,cursor

**Cross-agent translation** — rewrites a skill into another agent's format:

skillkit translate humanizar --to cursor
skillkit translate --all --to windsurf,codex
skillkit translate slop-eval --to copilot --dry-run

`skillkit recommend` suggests skills based on your project's stack, and `skillkit ui` opens an interactive TUI.

Via [Agent Skills CLI](https://www.agentskills.in/docs)

npm install -g agent-skills-cli

Then install the skills:

skills add https://github.com/fabricioctelles/skills

Or use without global install:

npx agent-skills-cli install https://github.com/fabricioctelles/skills

Manual Installation

1. Clone this repository:

git clone https://github.com/fabricioctelles/skills.git

2. Copy the desired skill folder to your agent's skills directory:

# Example for Cursor
cp -r skills/geo-optimization .cursor/skills/
cp -r skills/substack-expert .cursor/skills/
cp -r skills/pier-cloud .cursor/skills/
cp -r skills/ultimate-design-system-master .cursor/skills/
cp -r skills/resume-ats-beater .cursor/skills/
cp -r skills/coolify-operator .cursor/skills/
cp -r skills/agent-ready-cloudflare .cursor/skills/
cp -r skills/ralph-loop-kiro-specs .cursor/skills/
cp -r skills/loop-architect .cursor/skills/
cp -r skills/humanizar .cursor/skills/
cp -r skills/auth-md .cursor/skills/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 826 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. 🇧🇷 [Versao em Portugues do Brasil](README-PT-BR.md)
  2. [![skills.sh](https://skills.sh/b/fabricioctelles/skills)](https://skills.sh/fabricioctelles/skills)
  3. [![agentskill.sh](https://img.shields.io/badge/agentskill.sh-%40fabricioctelles-7C3AED)](https://agentskill.sh/@fabricioctelles)
  4. ![Cloudflare](https://img.shields.io/badge/Cloudflare-F38020?logo=cloudflare&logoColor=white)
  5. ![Astro](https://img.shields.io/badge/Astro-BC52EE?logo=astro&logoColor=white)
  6. ![Coolify](https://img.shields.io/badge/Coolify-6B16ED?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQTEwIDEwIDAgMCAwIDIgMTJhMTAgMTAgMCAwIDAgMTAgMTAgMTAgMTAgMCAwIDAgMTAtMTBBMTAgMTAgMCAwIDAgMTIgMnoiLz48L3N2Zz4=&logoColor=white)
  7. ![Google Analytics](https://img.shields.io/badge/Google%20Analytics-E37400?logo=googleanalytics&logoColor=white)
  8. ![Google Search Console](https://img.shields.io/badge/Search%20Console-458CF5?logo=google&logoColor=white)
  9. ![Substack](https://img.shields.io/badge/Substack-FF6719?logo=substack&logoColor=white)
  10. ![SEO](https://img.shields.io/badge/SEO%20%2F%20GEO-4285F4?logo=google&logoColor=white)
  11. ![AI Agents](https://img.shields.io/badge/AI%20Agents-8B5CF6?logo=openai&logoColor=white)
  12. ![TypeSafe Jev](https://img.shields.io/badge/TypeSafe%20Jev-10B981?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyTDIgN2wzIDEuNVYxN2w3IDQgNy00VjguNUwyMiA3bC0xMC01em0wIDIuMThMOSA2LjVsMyAxLjUgMy0xLjUtMy0yLjMyek01IDE2di01LjVsNiAzdjUuNWwtNi0zem04IDMuMXYtNS41bDYtM3Y1LjVsLTYgM3oiLz48L3N2Zz4=&logoColor=white)
  13. ![LGPD](https://img.shields.io/badge/LGPD%20%2F%20Privacy-059669?logo=shieldsdotio&logoColor=white)
  14. ![Security](https://img.shields.io/badge/Security-DC2626?logo=owasp&logoColor=white)
  15. # 🧠 AI Agent Skills — Open Source Collection for Claude Code, Cursor, Kiro & OpenCode
  16. 26 production-ready skills for AI coding agents. Install with one command, use across Claude Code, Cursor, Kiro, Windsurf, and OpenCode. Each skill teaches the agent to perform complex tasks — from rigorous engineering (pstack) to text humanization, SEO audits, and infrastructure automation.
  17. [Agent Skills](https://agentskills.io) are a lightweight, open format for extending AI agent capabilities. Each skill is a folder with a `SKILL.md` file containing metadata and instructions that agents load on demand. Learn more at [agentskills.io](https://agentskills.io/what-are-skills.md).
  18. ## OpenAI plugin: Deslop Writing
  19. [Deslop Writing](plugins/deslop-writing/README.md) bundles English (`human-ai`)
  20. and Brazilian Portuguese (`humanizar`) editing workflows in a portable plugin
  21. for ChatGPT and Codex, with no MCP server or external evaluator.
  22. ```bash
  23. codex plugin marketplace add fabricioctelles/skills --ref main
  24. codex plugin add deslop-writing@skilldev-pro
  25. ```
  26. Start a new session after installation, then ask Deslop Writing to edit your draft.
  27. ## 🧠 Skills with TypeSafe Jev Integration
  28. Four skills now support optional integration with [TypeSafe Jev](https://github.com/AugmentHCI/typesafe-jev) — a judgment engine that provides calibrated probability assessments (Score) and categorical classifications (Noul) for subjective evaluation criteria. When Jev is available, these skills use it for nuanced quality judgments; when unavailable, they fall back to heuristic methods.
  29. | Skill | Jev Use Case | Questions |
  30. |-------|--------------|-----------|
  31. | [humanizar](#-humanizar--ai-text-humanizer-for-brazilian-portuguese--code-quality-and-review) | Pattern severity, voice match quality, rewrite confidence | 8 Score + 12 Noul |
  32. | [human-ai](#-human-ai--ai-text-humanizer-for-english--code-quality-and-review) | Pattern severity, voice match quality, rewrite confidence | 8 Score + 12 Noul |
  33. | [slop-eval](#-slop-eval--design-slop-evaluator--code-quality-and-review) | Tell severity, axis quality, section classification | 8 Score + 16 Noul |
  34. | [agent-plugin-eval](#-agent-plugin-eval--product-verification) | UX coherence, documentation clarity, schema design, secret detection | 7 Score + 19 Noul |
  35. Each skill includes:
  36. - `scripts/jev_questions.json` — question definitions with context requirements
  37. - `references/jev-integration.md` — integration patterns and code examples
  38. - Discovery protocol in SKILL.md — check `jev_available()` before use
  39. ## Available Skills
  40. ### 💡 Startup Idea [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-startup-idea/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-startup-idea) · `data-fetching-and-analysis`
  41. Analyzes a startup idea through three lenses at once: Paul Graham (pressure test, founder-market fit, brutal validation), Dan Koe (monetization, offer, distribution, sales) and Seth Godin (differentiation, narrative, smallest viable audience). Delivers a pressure test, a monetization path, the minimum viable audience, a remarkability check and an action plan — not a generic canvas.
  42. **When to use:** validate a startup idea, pressure-test a business model, define the MVP, find the first customers, design the revenue model, plan go-to-market, chase product-market fit, or any variation of "I have an idea".
  43. 📄 [View full documentation](skills/startup-idea/SKILL.md)
  44. ---
  45. ### 🔍 GEO Optimization (Generative Engine Optimization) [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-geo-optimization/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-geo-optimization) · `code-quality-and-review`
  46. Optimizes digital content and marketing strategies for Generative Engines (LLMs, AI agents) to maximize citations in AI responses.
  47. **When to use:** improve visibility in AI responses (ChatGPT, Perplexity, Google AI Overview), measure citation rate, align terminology for LLMs, audit pages for AI, create optimized roundups and FAQs.
  48. **Improvements in v1.1 (Mar 2026):**
  49. - Moved Guiding Principles and case study context to `references/guiding-principles.md`
  50. - Fixed second-person language to imperative form throughout
  51. - Added explicit default action (Full GEO Audit) when no specific request is made
  52. - Converted Edge Cases section into a structured Quality Checklist with checkboxes
  53. - Description optimized to be more concise and actionable (Mar 8)
  54. 📄 [View full documentation](skills/geo-optimization/SKILL.md)
  55. ---
  56. ### 📰 Substack Expert [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-substack-expert/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-substack-expert) · `library-and-api-reference`
  57. Substack platform expert. Guides post formatting, SEO optimization (titles, slugs, meta descriptions), native engagement strategies (Notes, Chat), and conversion to paid subscriptions.
  58. **When to use:** format and optimize Substack posts, improve newsletter SEO (titles, slugs, meta descriptions), grow audience with Notes and recommendations, convert free readers to paid subscribers, customize homepage and welcome emails.
  59. **Improvements in v1.1 (Mar 2026):**
  60. - Removed duplicate Overview section and stray Portuguese artifact/orphaned code fence
  61. - Moved formatting tips to `references/formatting-best-practices.md`
  62. - Moved Input/Output Examples to `references/seo-output-example.md`
  63. - Added Parameters table with defaults for topic, goal, and language
  64. - Added explicit Clarify Scope step for ambiguous requests
  65. - Added Quality Checklist with 8 pre-delivery verification points
  66. 📄 [View full documentation](skills/substack-expert/SKILL.md)
  67. ---
  68. ### ☁️ Pier Cloud API [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-pier-cloud/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-pier-cloud) · `library-and-api-reference`
  69. Complete guide to consuming the [Pier Cloud](https://piercloud.com/en/) (Lighthouse) API with authentication, context management, workspaces, and data views.
  70. *Note: The documentation for this skill is in Portuguese, but it can be used in any language.*
  71. **When to use:** authenticate with Pier Cloud, list available contexts (AWS, etc), manage workspaces, access cost analysis views, run FinOps scripts.
  72. **Improvements in v1.1 (Mar 2026):**
  73. - Rewrote description to third-person trigger format
  74. - Removed verbatim Overview section that duplicated the frontmatter description
  75. - Fixed broken and incomplete Prerequisites section
  76. - Converted second-person language to imperative form throughout
  77. - Cleaned up workflow links to properly defer to `references/REFERENCE.md`
  78. - Added Quality Checklist
  79. 📄 [View full documentation](skills/pier-cloud/SKILL.md)
  80. ---
  81. ### 🎨 Ultimate Design System Master [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-ultimate-design-system-master/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-ultimate-design-system-master) · `code-scaffolding-and-templates`
  82. Generates Apple/Pentagram/frog/Vercel/Figma-level design deliverables using 10 specialized role-play prompts. Covers Design Systems, Brand Identity, UI/UX Patterns, Marketing Assets, Figma Specs, Design Critique, Trend Analysis, Accessibility Audit, Design-to-Code, and Executive Presentations.
  83. **When to use:** create a design system, build brand identity, generate UI/UX patterns, produce marketing assets, write Figma specs, get design critique, analyze design trends, run accessibility audit, translate design to code, create presentation decks.
  84. **Improvements in v2.1 (Mar 2026):**
  85. - Rewrote description to third-person trigger format
  86. - Moved 18-question Briefing Questionnaire to `references/briefing-questionnaire.md`
  87. - Added Quality Checklist with 5 concrete verification conditions
  88. - Removed intro sentence that duplicated frontmatter description
  89. **Improvements in v2.2 (Mar 8, 2026):**
  90. - Description rewritten with user-spoken trigger phrases for better skill activation
  91. - License Apache 2.0 added to metadata
  92. - Full compliance with Official Anthropic Guide for Agent Skills achieved
  93. 📄 [View full documentation](skills/ultimate-design-system-master/SKILL.md)
  94. ---
  95. ### 🗂️ Front-End Checklist _(moved)_
  96. > **This skill has been retired.** The original project now offers 385 self-contained skills (one per rule) covering HTML, CSS, JavaScript, Performance, Accessibility, SEO, Security, Images, Testing, Privacy, and Internationalization — far more complete than what we maintained here.
  97. >
  98. > 👉 **Install directly from:** https://github.com/thedaviddias/Front-End-Checklist/tree/main/skills
  99. >
  100. > ```bash
  101. > npx skills add frontendchecklist/skills
  102. > ```
  103. ---
  104. ### 🚀 Coolify Operator[^coolify-grade] · `ci-cd-and-deployment`
  105. Master operator for Coolify — the self-hosted open-source deployment platform (alternative to Heroku/Vercel/Netlify). Complete coverage of the official CLI with 100+ commands for managing applications, servers, databases, services, GitHub Apps, and cloud provider integrations.
  106. **When to use:** connect to Coolify instances, create/deploy/restart/stop applications, manage environment variables and storage, configure database backups, list servers and databases, monitor deployment logs, manage multiple environments (dev/staging/prod), integrate with GitHub Apps, provision servers on Hetzner/DigitalOcean/Vultr/Hostinger.
  107. **Key features:**
  108. - **Application creation** (5 methods): public repo, GitHub App, deploy key, Dockerfile, Docker image
  109. - **Full lifecycle management**: start, stop, restart, delete, move between environments
  110. - **Environment variables**: list, create, update, delete, sync from .env files
  111. - **Storage management**: persistent volumes, file mounts, directory mounts
  112. - **Database backups**: scheduled backups with S3/local retention, trigger on-demand
  113. - **Deploy module**: deploy by UUID, name, or batch multiple resources at once
  114. - **GitHub Apps**: create integrations, list accessible repos and branches
  115. - **Services (one-click)**: WordPress, Ghost, n8n, and 50+ more with sub-resource management
  116. - **Infrastructure**: destinations, cloud tokens (Hetzner/DO/Vultr/Hostinger), private keys, tags, Docker registry logins, server roles
  117. - **Restore & governance**: database import (file, upload, S3, server path), team audit log, Doppler/Infisical/Vault secret managers
  118. **New in v3.4 (Oct 29, 2026):**
  119. - Pinned to coolify-cli v1.11.0 and Coolify v4.5.3
  120. - Added `server hostinger catalog|data-centers|templates|ssh-keys|post-install-scripts` and `server hostinger create` (paid VPS purchase, confirmation prompt — never use `--force` in automation)
  121. - Documented sensitive-field masking in `table`, `json`, and `pretty` output, with `-s` to reveal; `context get` never prints the token
  122. - Added `--provider hostinger` to cloud token management
  123. **New in v3.3 (Oct 28, 2026):**
  124. - Reviewed Coolify v4.5.3: sensitive-data permissions, Cloudflare client IP allow-lists, service deletion change, timeout retry behavior
  125. - Documented CLI `mcp enable|disable`, MCP endpoint setup and token permissions
  126. - Added notes on preview variables, build fixes, update backups, server patching beta, and the v4.4.7 security update
  127. **New in v3.2 (Oct 19, 2026):**
  128. - Pinned to coolify-cli v1.10.0 and Coolify v4.4.6
  129. - Added `app previews list/get/create/update/logs` (full preview deployment CRUD + runtime logs)
  130. - Added `database import` and `service database import` (start/upload/status)
  131. - Added `audit list`, `integration-token create`, `app secret-manager set`
  132. - Added `server registry list/login/check/logout`, `server remove --force/--delete-from-provider`, `--server-role`
  133. - Documented the new `server get --resources` output (flat resource list)
  134. **New in v2.0 (Aug 15, 2026):**
  135. - Complete rewrite covering 100% of official Coolify CLI commands
  136. - Added `app create` (5 variants: public, github, deploy-key, dockerfile, dockerimage)
  137. - Added `app storage`, `app deployments`, `app previews`, `app tags`
  138. - Added `database create/backup/storage/env/tags` with full backup management
  139. - Added `service create --list-types`, `service application`, `service database` sub-resources
  140. - Added `deploy uuid/name/batch` module with `deploy list/get/cancel`
  141. - Added `github list/get/create/update/delete/repos/branches` for GitHub Apps
  142. - Added `projects`, `resources`, `tags`, `destinations`, `cloud-token`, `private-key`
  143. - Added LLM/AI Agent integration section with llms.txt references
  144. - Updated to match latest CLI documentation
  145. **Latest updates:** Image vulnerability scanning through the REST API and a GitLab App cloning workflow for supported Coolify versions.
  146. 📄 [View full documentation](skills/coolify-operator/SKILL.md)
  147. [^coolify-grade]: The Skills Directory assigned this skill **F (0/100)** after its automated scan flagged remote installer execution (`curl | bash`, `irm | iex`), private-key references, bearer-token API examples, destructive commands, and package installation. These pattern matches do not establish malicious intent: the API examples send credentials to the configured Coolify host, which the scanner cannot verify. Remote script execution and destructive commands still carry real risk; review them before use. See the [scan](https://www.skillsdirectory.com/skills/fabricioctelles-coolify-operator) and [scanning methodology](https://www.skillsdirectory.com/security/methodology).
  148. ---
  149. ### 📄 Resume ATS Beater + LinkedIn Optimizer [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-resume-ats-beater/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-resume-ats-beater) · `code-scaffolding-and-templates`
  150. Rewrites resumes for ATS compatibility and audits LinkedIn profiles for professional positioning. Covers CV optimization for Brazilian ATS platforms (Gupy, Vagas.com, PandaPé, Sólides) and LinkedIn audit with heuristic scoring, SSI analysis, fix prompts, and LLM rewrite mega-prompts. Works for any specialized profession — not dev-only.
  151. **When to use:** optimize resume for ATS, audit LinkedIn profile (headline, about, experiences, SSI), adapt CV to target role/industry, generate fix prompts per finding, align CV and LinkedIn in unified mode, improve bullets with measurable outcomes. Integrates with `humanizar` skill for narrative sections.
  152. **Improvements in v2.0 (Jun 2026):**
  153. - Added `modo_linkedin` (full profile audit with scoring) and `modo_unificado` (CV + LinkedIn with consistency check)
  154. - LinkedIn audit: headline format enforcement (Position | Areas | Tools·), about structure, experience bullets, language, skills, featured, SSI
  155. - Punitive scoring system: 100 - (critical×15 + warning×6 + info×2)
  156. - SSI analysis with 4 pillars, classification by tier, and actionable tips
  157. - Fix prompts per finding (standalone prompts for any LLM)
  158. - Mega-prompt for full profile rewrite by LLM
  159. - 18 career presets across tech, data, marketing, finance, engineering, legal, sales, HR, product
  160. - Integration with `humanizar` skill (scoped to About/Summary sections)
  161. - 3 new reference files: `auditoria-linkedin.md`, `ssi.md`, `presets-formatos.md`
  162. 📄 [View full documentation](skills/resume-ats-beater/SKILL.md)
  163. ---
  164. ### 🤖 Agent Ready — Cloudflare Scanner [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-agent-ready-cloudflare/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-agent-ready-cloudflare) · `product-verification`
  165. Audits any website for AI agent readiness using the Cloudflare [isitagentready.com](https://isitagentready.com) scanner. Scans 23 checks across 5 categories (Discoverability, Content, Bot Access Control, API/Auth/MCP Discovery, Commerce), assigns a level (0–5), and generates copy-paste fix prompts for every failing check. Includes 25 implementation sub-skills covering robots.txt, sitemap, Markdown for Agents, Content Signals, MCP Server Card, A2A Agent Card, Agent Skills Index, OAuth, WebMCP, and more.
  166. **When to use:** scan a site for agent readiness, check agent-ready score, fix failing checks, implement MCP Server Card, add Content Signals, publish Agent Skills index, set up Markdown for Agents, batch scan multiple domains, improve AI agent discoverability.
  167. 📄 [View full documentation](skills/agent-ready-cloudflare/README.md)
  168. ---
  169. ### ✅ DESIGN.md Validator [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-design-md-validator/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-design-md-validator) · `product-verification`
  170. Validates DESIGN.md files against the official [Google design.md specification](https://github.com/google-labs-code/design.md) using the `@google/design.md` CLI linter. Works with local files and remote URLs. Always uses `npx` to run the latest published version — never stale.
  171. **When to use:** lint a DESIGN.md for spec compliance, check WCAG contrast ratios, find broken token references, diff two design system versions, export tokens to Tailwind v3/v4 or W3C DTCG format, audit frontmatter schema.
  172. 📄 [View full documentation](skills/design-md-validator/SKILL.md)
  173. ---
  174. ### 🔁 Ralph Loop for Kiro Specs [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-ralph-loop-kiro-specs/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-ralph-loop-kiro-specs) · `code-scaffolding-and-templates`
  175. Automated iterative agent runner for spec-based development in [Kiro](https://kiro.dev). Wraps `kiro-cli` in a self-correcting bash loop that picks up tasks from a Kiro spec, implements them one at a time, verifies against exit criteria, and accumulates corrections and codebase patterns across iterations. Based on [ralph-loop-kiro-specs](https://github.com/mreferre/ralph-loop-kiro-specs) by [mreferre](https://github.com/mreferre).
  176. **When to use:** automate Kiro spec task implementation, run kiro-cli in a loop, drive a spec to completion through repeated agent iterations, set up or troubleshoot the Ralph Loop workflow, understand progress tracking, corrections, codebase patterns, and the summary dashboard.
  177. 📄 [View full documentation](skills/ralph-loop-kiro-specs/SKILL.md)
  178. ---
  179. ### 🏗️ Loop Architect — Agent Loop Design Coach [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-loop-architect/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-loop-architect) · `code-scaffolding-and-templates`
  180. Design well-structured agent loops with best-practice coaching and cross-model review gates before you run them. Interviews you, critiques your design against built-in rubrics, wires in reviewers/judges, and emits portable artifacts (`loop.yaml`, `RUN_IN_SESSION.md`, `run-loop.py`). Integrates natively with Kiro CLI's `/goal` and subagent review loops. Based on [Looper](https://github.com/ksimback/looper) by [Kevin Simback](https://github.com/ksimback).
  181. **When to use:** design an agent loop, set up a self-review or LLM-as-judge loop, build a multi-model council, create review-gated iterative workflows, or scaffold a `/goal`-driven process with typed verification and termination guards.
  182. 📄 [View full documentation](skills/loop-architect/SKILL.md)
  183. ---
  184. ### 👑 Pstack Skills — 23 Playbooks for Claude Code, Cursor & OpenCode [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-pstack-skill/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-pstack-skill) · `code-quality-and-review`
  185. Self-contained port of Lauren Tan's [pstack](https://github.com/cursor/plugins/tree/main/pstack) (`poteto-mode`) — 23 playbooks, 31 procedures, 24 engineering principles. No plugin install, no Cursor required. Runs in Claude Code, Cursor, Kiro, and OpenCode. One orchestrator that reads your task, picks the right playbook (bug fix, feature, refactoring, perf, investigation, prototype, babysit, shipping, autonomous run, orchestrate), routes to bundled procedures (how, why, architect, arena, swarm, interrogate, unslop, tdd), and applies engineering principles with traceable citations.
  186. **When to use:** any task that needs rigor — nontrivial code changes, architecture decisions, debugging with repro-first discipline, adversarial reviews, PR babysitting and shipping, long autonomous runs — or "poteto-mode", "work like poteto", "pstack". Works single-model; panels degrade to fresh-context passes without weakening any verification gate.
  187. **Version 1.7:** Model roles are provider-agnostic and use capabilities available in the current environment. `how` and `why` provide focused explanations, and statechart includes improved Mermaid rendering and SANY error reporting.
  188. 📄 [View full documentation](skills/pstack-skill/README.md)
  189. ---
  190. ### ✍️ Humanizar — AI Text Humanizer for Brazilian Portuguese [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-humanizar-skills/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-humanizar-skills) · `code-quality-and-review`
  191. Strips mechanical writing signals from Brazilian Portuguese text and restores rhythm, precision, and voice. Removes AI slop patterns, restores semantic entropy, and injects voice and personality. The goal is a better text, not a fooled detector: no rewrite can guarantee that a tool will classify the result as human, and the skill treats AI-detector scores as an invalid criterion. Born from the English `humanizer` skill but evolved into something far more complete — with 55+ patterns specific to PT-BR that no other source has cataloged.
  192. **Origin story:** I started from the English [humanizer](https://github.com/blader/humanizer) skill by [@blader](https://github.com/blader) (based on Wikipedia's "Signs of AI writing"), researched what makes AI text detectable specifically in Brazilian Portuguese, discovered there was *zero* consolidated material on PT-BR AI patterns, cataloged 55+ patterns from scratch (including 10 exclusive to Brazilian Portuguese like gerundismo, officialese, and ENEM-style hedging), incorporated the [tropes.fyi](https://tropes.fyi) directory and the concept of [semantic ablation](https://www.theregister.com/2026/02/16/semantic_ablation_ai_writing/) (The Register, 2026), and built a skill that doesn't just remove bad patterns — it restores the entropy that AI strips away.
  193. **Why it's better for PT-BR than the original:**
  194. - 55+ patterns vs 25 (including 10 that only exist in Brazilian Portuguese)
  195. - Semantic entropy restoration with explicit alerts (not just removal)
  196. - 6 voice presets calibrated for Brazilian contexts (crônica, journalistic, academic, corporate, social media, WhatsApp)
  197. - Examples are culturally Brazilian, not translations from English
  198. - Preserves naturalized foreign words (feedback, deploy, churn) — fighting linguistic purism is itself a humanization signal
  199. - Uses the Brazilian *crônica* literary tradition as the gold standard for natural writing
  200. **When to use:** humanize PT-BR text, remove AI slop, rewrite with voice, fix generic/bureaucratic tone, review text from another agent, "tirar cara de IA", "dar vida ao texto".
  201. **Improvements in v1.2 (Jun 2026):**
  202. - Added automatic document type detection with fallback (Step 0.5) — auto-selects the best voice preset
  203. - Added post-rewrite scoring with 5 weighted dimensions (Step 5.5) — quantifiable quality gate
  204. - Added iterative loop with strategy fallback — retries with different approaches when score < 60
  205. - Loop protocol compatible with external orchestrator skills (ralph-wiggum, goal)
  206. - Inspired by [humanize-it](https://github.com/smallnest/goal-workflow/blob/master/skills/humanize-it/SKILL.md) by [@smallnest](https://github.com/smallnest)
  207. **New in v1.3 (Jul 2026):**
  208. - Added **📋 Português Simplificado** voice profile — accessible writing inspired by PorSimples (NILC/USP) and Brazil's Lei 15.263/2025 (National Plain Language Policy)
  209. - 7 syntactic simplification operations based on PorSimples research (sentence splitting, passive→active, SVO reordering, discourse marker substitution, apposition removal, lexical simplification, subject explicitation)
  210. - New reference file `references/padroes-portugues-simplificado.md` with ~50 lexical substitutions, quantitative metrics from NILC-Metrix (ASL, TTR, syntactic complexity), 15 writing rules in 3 priority levels, and 4 application domains (government, health, tech, education)
  211. - Integration with TRAVA FACTUAL: explicit rules for when NOT to simplify (modality, causality, exceptions)
  212. - Now 10 voice profiles (was 9): Crônica, Jornalístico, Acadêmico, Corporativo Informal, Post de Rede Social, WhatsApp, Jurídico, Didático, **Português Simplificado**, and Voz Neutra
  213. **New in v1.5 (Sep 2026):**
  214. - 3 new **rapid-consumption profiles** inspired by the [Attention-Span](https://github.com/alexgreensh/attention-span) project: **➡️ Assertivo** (short paragraphs, arrows, bold lead-ins), **🔹 Enxuto** (facts only, checklists, zero fluff), and **📊 Resumo** (maximum compression for busy executives) — regras comuns adaptadas de [i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT)
  215. - New reference file `references/padroes-consumo-rapido.md` with formatting rules, cut rules, TRAVA FACTUAL integration, and verification checklist
  216. - Updated Step 1 (detection) with 3 new automatic signals
  217. - Updated Step 3 (references) with the new rapid-consumption reference
  218. - Updated Step 5 (voice application) with Apply/Avoid for all 3 profiles
  219. - Updated Step 6 (false-positive guard) with 6 specific exceptions: bold lead-ins, arrows, short sentences, checklists, long lists, and single-line paragraphs
  220. - Added brevity verification in Step 7 (5 items): propositions preserved, warnings not removed, scope not generalized, modality preserved, exact numbers kept
  221. - **TRAVA FACTUAL reinforced:** brevity compresses *form*, not *content* — never omit warnings, numbers, or scope conditions
  222. - Now **13 voice profiles** (was 10)
  223. **New in v1.4 (Aug 2026):**
  224. - Added **Step 6 — false-positive guard**, which runs before final verification and *unmarks* signals that are not AI at all: flawless grammar, dry prose, legal/academic register, dialogue em-dashes, isolated connectives, curly quotes on their own, correct commas, scoped hedging, real alternatives. Includes an explicit warning against AI-detector scores, which misfire against neurodivergent and non-native writers
  225. - Added **human marks to preserve** — contractions (`pra`, `tá`, `cê`), regionalisms (`uai`, `oxe`, `tchê`), mixed feelings, parenthetical self-correction, dated slang, sentence-length variation. The skill must not "fix" these by standardization
  226. - Added **`modo_criacao`** (writing from scratch): the pattern list becomes an output filter rather than a repair pass. Write first, then sweep — starting with the five patterns that account for most slips in new text
  227. - Five new patterns: fabricated source (a *specific* reference that does not exist — never repair it, flag it), title echo, false alternative rejected, documentation describing the previous version, and t-shirt maxim
  228. - Em-dash recalibrated from weight 1 to **weight 2**, with a mandatory sweep for `—`, `–` and ` -- ` before delivery, plus explicit exceptions (fiction dialogue, author sample)
  229. - Regression suite extended to T8 (human-mark preservation and fabricated-source handling)
  230. **Credits and sources for `humanizar`:**
  231. The false-positive guard, the human-marks list, the from-scratch writing mode and five patterns were incorporated from [PedroLLou/humanizador](https://github.com/PedroLLou/humanizador) (MIT), the Brazilian Portuguese version of [blader/humanizer](https://github.com/blader/humanizer) (MIT), which in turn derives from [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup.
  232. Portuguese-language sources behind those adaptations:
  233. - Marcelo Sabbatini, ["Texto chocho: como identificar a escrita da IA?"](https://iaedpraxis101.substack.com/p/texto-chocho-como-identificar-a-escrita), IAEdPraxis — source for *crucial* and *mergulhar* as PT-BR markers, generic adjectives, the serial comma and the period-inside-quotes convention
  234. - Marina Semensato, ["Como saber se um texto foi feito por inteligência artificial?"](https://exame.com/tecnologia/examelab/como-saber-se-um-texto-foi-feito-por-inteligencia-artificial/), Exame — connective overuse, conclusions that only restate the text, forced triads and "não é X, é Y"
  235. - [Inteligência artificial na Wikimedia](https://pt.wikipedia.org/wiki/Intelig%C3%AAncia_artificial_na_Wikimedia), Portuguese Wikipedia — em-dash overuse, "além disso" overuse, promotional material, curly quotes and non-existent references
  236. - Pew Research Center, ["How Much of the Internet Is Written With AI?"](https://www.pewresearch.org/data-labs/2026/08/20/how-much-of-the-internet-is-written-with-ai/) (2026) — measures the growth of em-dashes, serial commas and negative parallelism. **The sample covers English-language pages only**, so it is evidence of the mechanism, not of Portuguese
  237. **Confidence levels.** No single pattern proves artificial origin; the signal is accumulation. These have direct support in published Portuguese sources or in released measurements: AI vocabulary, negative parallelism ("não apenas X, mas Y"), the aparte em-dash, decorative emoji, curly quotes, chatbot leftovers, stacked connectives, English-imported punctuation and fabricated sources. The rest are heuristics, not proof.
  238. The **Português Simplificado** profile derives its operations from the PorSimples project (NILC/USP) and the techniques associated with Brazil's Lei 15.263/2025 (National Plain Language Policy).
  239. 📄 [View full documentation](skills/humanizar/SKILL.md)
  240. ---
  241. ### 🌐 Human-AI — AI Text Humanizer for English [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-human-ai-skills/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-human-ai-skills) · `code-quality-and-review`
  242. Strips mechanical writing signals from English text and restores rhythm, precision, and voice. Combines pattern detection (43 patterns across 3 tiers), statistical rhythm measurement (burstiness, TTR, entropy), and voice injection into a single iterative skill. Built on research from the RAID Benchmark (ACL 2024) and NeurIPS 2023. Same positioning as `humanizar`: the metrics are measurable proxies for natural rhythm, not a scoreboard to beat, and detector scores never decide what gets rewritten.
  243. **Origin story:** Companion to the PT-BR `humanizar` skill, but 100% original English work. Synthesizes the best of three open-source humanizer skills: [blader/humanizer](https://github.com/blader/humanizer) (10.6K stars, 29 patterns), [brandonwise/humanizer](https://github.com/brandonwise/humanizer) (560-term vocab filter, statistical signals), and [Aboudjem/humanizer-skill](https://github.com/Aboudjem/humanizer-skill) (43 patterns, P31-P43 emerging 2026 discoveries). Goes beyond all three by adding: research-calibrated empirical baselines, iterative scoring with strategy fallback, 7 voice presets, a `scripts/measure.py` for deterministic metrics, and the critical insight that synonym-swapping changes nothing while structural paraphrasing does — the RAID study measured that as detector accuracy dropping from 70.3% to 4.6%, which is evidence about rhythm and sentence architecture, not a goal in itself.
  244. **Why it's different from the existing humanizer skills:**
  245. - 43 patterns (including P31-P43 emerging patterns from 2026 community research)
  246. - Research-backed metrics: TTR human 0.553 vs AI 0.455 (SSRN), burstiness +0.70 vs 0.00 (GPTZero)
  247. - `scripts/measure.py` — deterministic TTR/burstiness/entropy calculation (zero dependencies)
  248. - 7 voice presets calibrated for English contexts (essay, journalistic, academic, corporate, social, casual, legal, instructional)
  249. - Anti-synonym-swap enforcement: Step 2 requires full sentence restructuring, not word replacement
  250. - 7 documented gotchas from real-world humanizer skill failures
  251. - Iterative loop with scoring (0-100) and strategy fallback table
  252. - Composes with external loop skills (ralph-wiggum, goal)
  253. **When to use:** humanize English text, remove AI slop, de-slop content, make text sound human, add voice, fix bland/generic tone, bypass AI detection, pass GPTZero/Originality.ai, review text from another agent, rewrite naturally.
  254. 📄 [View full documentation](skills/human-ai/SKILL.md)
  255. ---
  256. ### 🔐 auth.md — Agent Authentication Protocol [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-auth-md-skills/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-auth-md-skills) · `library-and-api-reference`
  257. Generates, validates, and explains [auth.md](https://auth-md.com) files — the open protocol that lets AI agents register for services on behalf of users without signup forms. Supports the Agent Verified flow (ID-JAG identity assertions via trusted providers like OpenAI, Anthropic, Cursor) and the User Claimed flow (OTP-based registration with anonymous start or email required entrypoints). Extends RFC 9728 (Protected Resource Metadata) with CIMD support.
  258. **When to use:** make your app agent-ready by publishing an `auth.md`, generate Protected Resource Metadata and Authorization Server metadata with `agent_auth` block, validate an existing `auth.md` against the protocol spec, implement agent registration endpoints (`/agent/auth`, `/agent/auth/claim`, `/agent/auth/revoke`), understand how the auth.md protocol works, configure ID-JAG verification and trust lists, set up OTP claim ceremonies.
  259. 📄 [View full documentation](skills/auth-md/SKILL.md) | 🌐 [auth-md.com](https://auth-md.com)
  260. ---
  261. ### 📦 OKF — Open Knowledge Format [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-okf-open-knowledge-format/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-okf-open-knowledge-format) · `library-and-api-reference`
  262. Create, validate, and enrich [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundles — the open spec (v0.1, announced June 12, 2026 by Sam McVeety & Amir Hormati at Google Cloud) that formalizes the "LLM Wiki" pattern into a portable, interoperable format for organizational knowledge. Markdown files with YAML frontmatter, consumable by any AI agent without SDK. Includes bash validator, conversion guides (Notion, Obsidian, CSV), and integration with Google Cloud Knowledge Catalog via kcmd CLI/MCP.
  263. **When to use:** create OKF bundles, validate conformance, enrich concepts with schema/citations/cross-links, convert existing knowledge (Notion exports, Obsidian vaults, spreadsheets) to OKF, structure a knowledge base for AI agent consumption, generate index.md and log.md files, push bundles to Knowledge Catalog via kcmd.
  264. 📄 [View full documentation](skills/okf-open-knowledge-format/SKILL.md) | 🌐 [okf.md](https://okf.md)
  265. ---
  266. ### 🌐 Website Spec _(moved)_
  267. > **This skill has been retired.** The original project now offers a more complete skill with 140+ topics, live updates via MCP server, delta re-audits, and MDN pairing — far beyond what we maintained here.
  268. >
  269. > 👉 **Use the official skill:** https://specification.website/.well-known/agent-skills/specification-website/SKILL.md
  270. >
  271. > MCP endpoint: `https://mcp.specification.website/mcp`
  272. ---
  273. ### 🔒 LGPD Check
  274. > **Migrated** → This skill moved to [github.com/lgpd-app/skills](https://github.com/lgpd-app/skills)
  275. Audits websites for compliance with Brazil's LGPD (Lei 13.709/2018).
  276. ---
  277. ### 🔒 LGPD.md
  278. > **Migrated** → This skill moved to [github.com/lgpd-app/skills](https://github.com/lgpd-app/skills)
  279. Generates and validates `lgpd.md` files — the LGPD compliance declaration standard.
  280. ---
  281. ### 📊 Skill Evaluation [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-skill-evaluation/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-skill-evaluation) · `code-quality-and-review`
  282. Evaluate any agent skill against a merged framework — Anthropic's Claude Code best practices plus Matt Pocock's writing-great-skills methodology — across 4 axes (Trigger, Structure, Steering, Pruning). Produces an evidence-cited scorecard (0–100), a weighted overall score, and diagnosed failure modes with prioritized fixes.
  283. **v2.2 — Trigger Eval (empirical):** now includes an empirical trigger-testing step inspired by Philipp Schmid's (Google DeepMind) talk ["Don't Ship Skills Without Evals"](https://www.youtube.com/watch?v=0vphxNt4wyk). Generates 5 should-trigger + 5 should-not-trigger prompts, runs them via independent sub-agents, and measures whether the skill's description actually causes invocation — bridging the gap between static quality analysis and runtime validation.
  284. **When to use:** evaluate a skill, rate skill quality, audit SKILL.md, compare two skills, skill scorecard, review best practices compliance, or check if a skill is production-ready.
  285. **18 scored criteria across 4 axes:** Invocation design · Description quality · Steps vs. reference clarity · Branch-aware disclosure · Conciseness · Coherent scope · Leading words · Completion criteria · Gotchas · Grounded in expertise · Avoids railroading · No-ops · Single source of truth · Relevance & sediment + 4 conditional (Setup flow · Memory · Scripts · Hooks)
  286. **5 bonus patterns (measured, not scored):** Validation loops · Output templates · Procedures over declarations · Defaults over menus · Trace-checkable steering
  287. **How it differs from [agentskills.io evals](https://agentskills.io/skill-creation/evaluating-skills) and [skill-creator benchmark](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills):**
  288. | | This skill | agentskills.io evals | skill-creator benchmark |
  289. |---|---|---|---|
  290. | Evaluates | Skill **structure** quality + **trigger** empirically | Skill **output** quality | Output + regression + obsolescence |
  291. | Method | Static inspection + sub-agent trigger eval | Run test cases + grade | A/B blind comparison + multi-agent |
  292. | When | Is it well-built? Does it trigger correctly? | Does it work? | Did it regress? Still needed? |
  293. | Output | Scorecard + grade A-F + trigger hit/leak rates | pass_rate, tokens, time | benchmark.json + comparator verdict |
  294. | Platform | Any agent | Any agent | Claude Code only (plugin) |
  295. Use in sequence: **skill-evaluation** (design review + trigger testing) → **evals** (functional validation) → **benchmark** (ongoing monitoring).
  296. 📄 [View full documentation](skills/skill-evaluation/SKILL.md)
  297. ---
  298. ### 🧹 Slop Eval — Design Slop Evaluator [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-slop-eval/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-slop-eval) · `code-quality-and-review`
  299. Objectively evaluates a UI/web design against [the pols.dev anti-slop design law](https://pols.dev/slop.md): sweeps an ID'd catalog of slop tells across 6 families (color & light, typography, components, layout, motion, execution), checks 6 absolute execution rules, and scores 8 weighted axes — including a 3x-weighted Signature axis with a hard gate, so a "clean but empty" page can't hide behind restraint. Emits a Slop Report with a 0–100 Slop Index and grade A–F. Every finding follows **cite-or-cut**: no concrete evidence (hex value, font name, file:line, screenshot region), no tell.
  300. **How it evaluates:** live URL (browser-automation SOP: dual-viewport full-page captures, interaction pass, zoom crops), static screenshots, code path (grep-led sweep), or Figma export — anything not observable is marked Unverifiable, never guessed. Deterministic scoring via `scripts/score.py`, with a `--fail-below` CI gate for blocking PRs on preview-deploy design quality.
  301. **When to use:** evaluate design slop, generate a slop report, check if a design looks AI-generated or generic, audit a landing page design, de-slop review, compare two designs (before/after), track design evolution over time.
  302. **New in v1.1.0 (Aug 2026):**
  303. - **Section Ledger:** per-section verdicts (CLEAN/SUSPICIOUS/INFLATED/CRITICAL) with tell density bands and action recommendations
  304. - **Design Contexts:** context-aware evaluation for landing pages, SaaS dashboards, editorial, and e-commerce — adjusts priority tells and tolerances per design type
  305. - **Exclusion System:** formalized `// BRIEF:`, `// DESIGN DECISION:`, `// CONTEXT:`, `// PREMIUM PAIR:` tags for documenting excluded tells with audit trail
  306. - **Tracking Mode:** temporal evolution analysis with tells resolved/introduced, regressions, velocity metrics, and recommendations for next iteration
  307. - **Adding Soul Guide:** prescription-oriented guide for injecting personality into each axis — not just "remove tell X" but "replace with premium alternative Y"
  308. - **Expanded Quality Checklist:** 25+ checks across 6 phases (pre-sweep, during-sweep, exclusion, post-sweep, report, self-audit) including portability and defense tests
  309. **Companions:** method inspired by [skill-evaluation](skills/skill-evaluation/SKILL.md); for text (not design), [human-ai](skills/human-ai/SKILL.md) and [humanizar](skills/humanizar/SKILL.md) do the de-slopping.
  310. 📄 [View full documentation](skills/slop-eval/SKILL.md)
  311. ---
  312. ### 🛡️ Security Specialist [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-security-specialist/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-security-specialist) · `runbooks`
  313. Full-stack application security agent — performs SAST (static code analysis), DAST (dynamic testing against running apps), threat modeling, vulnerability triage, remediation, and penetration testing. Combines source code review with live testing against local dev servers or production targets for complete evidence correlation.
  314. **When to use:** security scan a repository, review a PR for security issues, build a threat model, triage vulnerability findings, fix a security bug, pentest a web application, validate a security fix, track findings to GitHub/Jira/Linear, generate a security report.
  315. **Key features:**
  316. - **Input-driven SOP**: path only → SAST + dev DAST; path + URL → SAST + dev + prod; URL only → DAST
  317. - **12 steering workflows**: full-scan, diff-review, pentest, hunting, threat-model, attack-paths, discovery, triage, remediation, tracking, validation, reporting
  318. - **6-phase pipeline** (full-scan): Recon → Hunt → Validate → Report → Schema → Verify — with parallel agents and adversarial validation
  319. - **9 attack classes**: Injection, Access Control, Resource/File, Cryptography, Business Logic, Feature Abuse, Chained Attacks, Wildcard, Obvious Things
  320. - **12-angle hunting methodology**: sad path, boundaries, component assumptions, wrong ordering, concurrency, parser disagreements, round-trip fidelity, config control, privilege tracing, leaked context, parameter overrides, unverified claims
  321. - **Adversarial validation**: separate agents try to DISPROVE findings (5 gates: exploitation, impact, baseline, mitigation, parser/runtime)
  322. - **Structured JSON output**: findings.json validated against JSON schema with trace (entrypoint→propagation→sink), conditions, execution, confidence
  323. - **Schema validator**: zero-dependency Node.js script (`validate-findings.cjs`) for CI integration
  324. - **Multi-run additive coverage**: each run targets gaps from prior runs; single run finds ~50% of total vulnerabilities
  325. - **5 utility scripts**: SQLite scan DB, file ranker, report finalizer, pentest automation, schema validator
  326. - **Pentest tool cascade**: nmap → python-nmap → socket scan; nikto → wapiti3 → header checks; gobuster → dirsearch → urllib brute
  327. - **Three-layer correlation**: source finding → dev exploit → prod confirmation
  328. - **Dynamic baseline calibration**: compares patterns against industry-standard comparable applications
  329. **Architecture:**
  330. ```
  331. security-specialist/
  332. ├── SKILL.md (router + core principles + anti-patterns)
  333. ├── steering/ (12 workflow docs including hunting methodology)
  334. ├── scripts/ (5 tools: Python + Node.js validator)
  335. └── references/ (5 spec docs: finding format, report format, severity policy, artifacts, report-schema.json)
  336. ```
  337. **Improvements in v2.0 (Jun 2026):**
  338. - Added 6-phase audit pipeline with parallel agents (inspired by Cloudflare security-audit-skill)
  339. - Added `steering/hunting.md` with 9 attack classes and 12-angle hunting methodology
  340. - Added adversarial validation (Phase 3) and independent verification (Phase 6)
  341. - Added `references/report-schema.json` for structured findings with trace, conditions, execution, confidence
  342. - Added `scripts/validate-findings.cjs` zero-dependency JSON schema validator
  343. - Added multi-run additive coverage strategy
  344. - Added 10 anti-patterns to avoid in security audits
  345. - Added dynamic baseline calibration to severity policy
  346. - Enhanced finding format: simple (SQLite) + structured (JSON pipeline) dual format
  347. 📄 [View full documentation](skills/security-specialist/SKILL.md)
  348. ---
  349. ### 🚀 Astro Sites Manager [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-astro-sites-manager/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-astro-sites-manager) · `ci-cd-and-deployment`
  350. Comprehensive skill for building, migrating, and maintaining Astro v7 projects. Covers the full lifecycle: best practices, v6→v7 migration with structured plan, validation of breaking/deprecated patterns, AI-enhanced dev server (background mode, JSON logging), advanced routing with src/fetch.ts, route caching, Sätteri Markdown, Rust compiler, Starlight docs, Pagefind search, SEO, testing, and deployment to 8+ platforms including Coolify.
  351. **When to use:** build Astro sites, upgrade to v7, deploy on Coolify/Vercel/Netlify/Cloudflare, validate breaking changes, configure Starlight docs, set up Pagefind search, use background dev server as AI agent, configure route caching.
  352. **Key features:**
  353. - MCP Astro Docs integration (real-time docs access)
  354. - 10 reference files covering migration, validation, testing, deployment, Starlight, and more
  355. - Coolify-specific deployment guide with 17-project battle-tested patterns
  356. - Feature detection: v7 features activate only when available (safe on v6)
  357. 📄 [View full documentation](skills/astro-sites-manager/SKILL.md)
  358. ---
  359. ### 🔌 Agent Plugin Eval [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-agent-plugin-eval/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-agent-plugin-eval) · `product-verification`
  360. Audits, scores, and compares repositories containing portable Agent Plugins against the official [Agent Plugins specification](https://agent-plugins.org). Produces an evidence-cited 0–100 scorecard with conformance gate (PASS/PARTIAL/FAIL), identifies release blockers, and compares two plugins side by side. Works with any agent client — evaluates portable conformance, not client-specific features.
  361. **When to use:** audit a plugin repo, check plugin.json or mcp.json conformance, validate bundled Agent Skills, assess MCP server configurations, produce a plugin scorecard, identify release blockers, compare two agent plugins.
  362. **Key features:**
  363. - Static-only audit (never executes plugin code, MCP servers, or scripts)
  364. - 18-criterion rubric across 4 axes: Portable conformance, Components & integration, Safety & resilience, Product quality
  365. - Conformance gates: PASS (no cap), PARTIAL (capped at 59), FAIL (capped at 39)
  366. - Deterministic scoring via `scripts/score.py`
  367. - Comparison mode for evaluating two plugins side by side
  368. - Client-agnostic: evaluates against portable spec, not Codex/Claude/Cursor-specific features
  369. 📄 [View full documentation](skills/agent-plugin-eval/SKILL.md)
  370. ---
  371. ### 💰 Revenue-Centric Design [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-revenue-centric-design/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-revenue-centric-design) · `runbooks`
  372. Playbook of 134 evidence-backed principles for designing SaaS and startup products that convert, retain, and monetize — landing pages & CRO, checkout/forms, dashboards/data viz, onboarding/activation, churn reduction, pricing psychology, behavioral science, feature discipline, positioning/ICP, go-to-market, and AI-era differentiation. Every principle names its mechanism (decoy effect, Zeigarnik, Schwartz awareness levels…) and links back to its source post. Ships with revenue-math scripts (A/B sample size, churn→LTV, CAC per closed deal), an audit output template, per-project memory (`rcd-log.md`), and license-enforcing guardrail hooks.
  373. **Origin story:** Richard ([@richardrx](https://x.com/richardrx), "Design for startups" — ex-Volkswagen, PayPal, IBM) published these principles as posts in Portuguese on X (134 principles in the current catalog). [Helio Costa](https://github.com/heliocosta-dev) obtained the author's permission, extracted the posts via the X API, translated them to English, and distilled them into the original skill ([heliocosta-dev/revenue-centric-design](https://github.com/heliocosta-dev/revenue-centric-design)). This repository hosts an evolved derivative of that work.
  374. **Evolution measured with [skill-evaluation](skills/skill-evaluation/SKILL.md):** the as-downloaded skill scored **60/100 (B, borderline C)**; one improvement pass later, **73/100 (B)**:
  375. | Criterion | before | after |
  376. |---|---|---|
  377. | Scripts & libraries | 0 | 75 |
  378. | Gotchas section | 35 | 88 |
  379. | Coherent scope | 55 | 72 |
  380. | Progressive disclosure | 78 | 90 |
  381. | Description for trigger | 78 | 90 |
  382. | Repo footprint | 39 MB | 176 KB |
  383. After the compared run, the skill also gained the audit template, the project log, full license compliance, and hook-based guardrails — each closing a finding the scorecard had prioritized. This is exactly the loop skill-evaluation was built for: **evaluate → fix the top findings → re-evaluate → compare.**
  384. **When to use:** improve conversion on a landing page, fix activation/onboarding, reduce churn, design pricing tables and upgrade paths, sharpen ICP/positioning, apply behavioral-science mechanisms, sanity-check A/B tests, differentiate in the AI era.
  385. **⚠️ License:** source-available, **not** Apache 2.0 — attribution to @richardrx required, and **gambling/betting/casino use is prohibited** (enforced at runtime by bundled hooks). See the [skill's LICENSE](skills/revenue-centric-design/LICENSE).
  386. 📄 [View full documentation](skills/revenue-centric-design/SKILL.md)
  387. ---
  388. ### 🎬 Motion Ad [![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/fabricioctelles-motion-ad/badge)](https://www.skillsdirectory.com/skills/fabricioctelles-motion-ad) · `code-scaffolding-and-templates`
  389. Produces a short motion-graphics video ad — a 15s Facebook/Instagram/TikTok spot — as a rendered MP4. Researches the destination landing page so every on-screen claim matches it, pulls real product imagery off the live site, animates one paused GSAP timeline in a single HTML page, and renders it frame-accurately through Playwright and ffmpeg. Ships a finished 15s 4:5 ad as a template (hook + phone → before/after scan reveal → 3D wall of outputs → showcase carousel + proof → CTA end card) whose entire brand and product content lives in one `CONFIG` object.
  390. **When to use:** make a video ad, promo video or animated ad, produce Meta/TikTok/Reels creative in video form, cut a 9:16 or 1:1 version of a spot, or re-render an earlier ad with a different hook, hero or CTA.
  391. **Key features:**
  392. - **Frame-accurate, not screen-recorded** — `render.cjs` seeks the paused timeline per frame, so re-renders are deterministic
  393. - **Claims verified against the destination page** — prices, counts and "free" claims have to exist on the landing page
  394. - **Real assets only** — scrapes the product's own imagery; nothing invented, and `proof: null` drops the social-proof row when there's no real number
  395. - **Rewriting beats, not building from zero** — `references/template-map.md` maps every `CONFIG` field, DOM id and geometry constant, with recipes for cutting a beat, adding one, and re-laying out to 9:16, 1:1 or 2×
  396. - **Review loop built in** — contact-sheet tooling tiles assets and render stills into one JPG so a whole pass is checked in a single read
  397. **⚠️ License:** [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — **not** Apache 2.0. Created by [danny.md](https://www.danny.md/skills/motion-ad): free to use and remix, **not to sell**. This copy adds repo-standard metadata, portable skill-path resolution, a preflight check and `references/template-map.md`.
  398. 📄 [View full documentation](skills/motion-ad/SKILL.md)
  399. ---
  400. > **Skills revised in March 2026** following the Anthropic standard for Agent Skills structure and quality.
  401. > Source: [Improving Skill Creator: Test, Measure and Refine Agent Skills](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)
  402. ## Installation
  403. You can install these skills using any compatible installer or manually. Below are the most popular options.
  404. ### Via [Skills.sh](https://skills.sh/docs)
  405. ```bash
  406. npx skills add https://github.com/fabricioctelles/skills
  407. ```
  408. Or install a specific skill:
  409. ```bash
  410. npx skills add https://github.com/fabricioctelles/skills -s startup-idea
  411. npx skills add https://github.com/fabricioctelles/skills -s revenue-centric-design
  412. npx skills add https://github.com/fabricioctelles/skills -s geo-optimization
  413. npx skills add https://github.com/fabricioctelles/skills -s substack-expert
  414. npx skills add https://github.com/fabricioctelles/skills -s humanizar
  415. npx skills add https://github.com/fabricioctelles/skills -s human-ai
  416. npx skills add https://github.com/fabricioctelles/skills -s pier-cloud
  417. npx skills add https://github.com/fabricioctelles/skills -s coolify-operator
  418. npx skills add https://github.com/fabricioctelles/skills -s astro-sites-manager
  419. npx skills add https://github.com/fabricioctelles/skills -s security-specialist
  420. npx skills add https://github.com/fabricioctelles/skills -s ultimate-design-system-master
  421. npx skills add https://github.com/fabricioctelles/skills -s design-md-validator
  422. npx skills add https://github.com/fabricioctelles/skills -s skill-evaluation
  423. npx skills add https://github.com/fabricioctelles/skills -s slop-eval
  424. npx skills add https://github.com/fabricioctelles/skills -s agent-plugin-eval
  425. npx skills add https://github.com/fabricioctelles/skills -s agent-ready-cloudflare
  426. npx skills add https://github.com/fabricioctelles/skills -s auth-md
  427. npx skills add https://github.com/fabricioctelles/skills -s pstack-skill
  428. npx skills add https://github.com/fabricioctelles/skills -s okf-open-knowledge-format
  429. npx skills add https://github.com/fabricioctelles/skills -s ralph-loop-kiro-specs
  430. npx skills add https://github.com/fabricioctelles/skills -s loop-architect
  431. npx skills add https://github.com/fabricioctelles/skills -s resume-ats-beater
  432. ```
  433. ### Via [SkillKit](https://github.com/rohitg00/skillkit)
  434. A package manager for skills with cross-agent translation. Runs with zero install:
  435. ```bash
  436. npx skillkit add fabricioctelles/skills
  437. ```
  438. Or install the CLI globally:
  439. ```bash
  440. npm install -g skillkit # full
  441. npm install -g skillkit --omit=optional # slim, ~75% smaller, no native addons
  442. skillkit install fabricioctelles/skills
  443. ```
  444. Target specific agents (46 supported, including Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Copilot, OpenCode, Kiro):
  445. ```bash
  446. skillkit install fabricioctelles/skills --agent claude-code,cursor
  447. ```
  448. **Cross-agent translation** — rewrites a skill into another agent's format:
  449. ```bash
  450. skillkit translate humanizar --to cursor
  451. skillkit translate --all --to windsurf,codex
  452. skillkit translate slop-eval --to copilot --dry-run
  453. ```
  454. `skillkit recommend` suggests skills based on your project's stack, and `skillkit ui` opens an interactive TUI.
  455. ### Via [Agent Skills CLI](https://www.agentskills.in/docs)
  456. ```bash
  457. npm install -g agent-skills-cli
  458. ```
  459. Then install the skills:
  460. ```bash
  461. skills add https://github.com/fabricioctelles/skills
  462. ```
  463. Or use without global install:
  464. ```bash
  465. npx agent-skills-cli install https://github.com/fabricioctelles/skills
  466. ```
  467. ### Manual Installation
  468. 1. Clone this repository:
  469. ```bash
  470. git clone https://github.com/fabricioctelles/skills.git
  471. ```
  472. 2. Copy the desired skill folder to your agent's skills directory:
  473. ```bash
  474. # Example for Cursor
  475. cp -r skills/geo-optimization .cursor/skills/
  476. cp -r skills/substack-expert .cursor/skills/
  477. cp -r skills/pier-cloud .cursor/skills/
  478. cp -r skills/ultimate-design-system-master .cursor/skills/
  479. cp -r skills/resume-ats-beater .cursor/skills/
  480. cp -r skills/coolify-operator .cursor/skills/
  481. cp -r skills/agent-ready-cloudflare .cursor/skills/
  482. cp -r skills/ralph-loop-kiro-specs .cursor/skills/
  483. cp -r skills/loop-architect .cursor/skills/
  484. cp -r skills/humanizar .cursor/skills/
  485. cp -r skills/auth-md .cursor/skills/
  486. cp -r skills/astro-sites-manager .cursor/skills/
  487. cp -r skills/agent-plugin-eval .cursor/skills/
  488. # Example for Claude Code
  489. cp -r skills/geo-optimization .claude/skills/
  490. cp -r skills/substack-expert .claude/skills/
  491. cp -r skills/pier-cloud .claude/skills/
  492. cp -r skills/ultimate-design-system-master .claude/skills/
  493. cp -r skills/resume-ats-beater .claude/skills/
  494. cp -r skills/coolify-operator .claude/skills/
  495. cp -r skills/agent-ready-cloudflare .claude/skills/
  496. cp -r skills/ralph-loop-kiro-specs .claude/skills/
  497. cp -r skills/loop-architect .claude/skills/
  498. cp -r skills/humanizar .claude/skills/
  499. cp -r skills/auth-md .claude/skills/
  500. cp -r skills/astro-sites-manager .claude/skills/
  501. cp -r skills/agent-plugin-eval .claude/skills/
  502. # Example for Kiro
  503. cp -r skills/geo-optimization .kiro/skills/
  504. cp -r skills/substack-expert .kiro/skills/
  505. cp -r skills/pier-cloud .kiro/skills/
  506. cp -r skills/ultimate-design-system-master .kiro/skills/
  507. cp -r skills/resume-ats-beater .kiro/skills/
  508. cp -r skills/coolify-operator .kiro/skills/
  509. cp -r skills/agent-ready-cloudflare .kiro/skills/
  510. cp -r skills/ralph-loop-kiro-specs .kiro/skills/
  511. cp -r skills/loop-architect .kiro/skills/
  512. cp -r skills/humanizar .kiro/skills/
  513. cp -r skills/auth-md .kiro/skills/
  514. cp -r skills/astro-sites-manager .kiro/skills/
  515. cp -r skills/agent-plugin-eval .kiro/skills/
  516. ```
  517. The Agent Skills format is universal and works with any compatible agent. See the [official specification](https://agentskills.io/specification.md) for details.
  518. ## Repository Structure
  519. ```
  520. skills/
  521. ├── startup-idea/
  522. │ ├── SKILL.md
  523. │ └── evals/ # 3 lenses: Graham, Koe, Godin
  524. ├── revenue-centric-design/
  525. │ ├── SKILL.md
  526. │ ├── references/ # 134 principles + audit output template
  527. │ └── scripts/ # revenue math: A/B sample size, churn to LTV, CAC
  528. ├── geo-optimization/
  529. │ ├── SKILL.md
  530. │ └── references/ # guiding principles and case studies
  531. ├── substack-expert/
  532. │ ├── SKILL.md
  533. │ └── references/ # formatting best practices, SEO output example
  534. ├── humanizar/
  535. │ ├── SKILL.md
  536. │ └── references/ # 55+ AI patterns specific to Brazilian Portuguese (7 files)
  537. ├── human-ai/
  538. │ ├── SKILL.md
  539. │ ├── references/ # 43 EN patterns, empirical baselines
  540. │ └── scripts/ # measure.py — deterministic metrics
  541. ├── pier-cloud/
  542. │ ├── SKILL.md
  543. │ ├── scripts/ # Python scripts for API consumption
  544. │ └── references/ # API reference, troubleshooting guide
  545. ├── coolify-operator/
  546. │ ├── SKILL.md
  547. │ └── evals/ # 8 test scenarios
  548. ├── astro-sites-manager/
  549. │ ├── SKILL.md
  550. │ └── references/ # Astro v7 migration, routing, deploy targets
  551. ├── security-specialist/
  552. │ ├── SKILL.md
  553. │ ├── steering/ # 12 workflow docs including hunting methodology
  554. │ ├── scripts/ # 5 tools: Python + Node.js validator
  555. │ └── references/ # 5 spec docs: finding/report format, severity policy
  556. ├── ultimate-design-system-master/
  557. │ ├── SKILL.md
  558. │ └── references/ # briefing questionnaire, 10 specialized prompt files
  559. ├── design-md-validator/
  560. │ ├── SKILL.md
  561. │ └── references/ # Google DESIGN.md spec, lint rules, export formats
  562. ├── skill-evaluation/
  563. │ ├── SKILL.md
  564. │ ├── references/ # 18 criteria across 4 axes, scorecard template
  565. │ └── scripts/ # trigger eval runner
  566. ├── slop-eval/
  567. │ ├── SKILL.md
  568. │ ├── references/ # 8 axes of the anti-slop law
  569. │ └── scripts/ # Slop Index calculator
  570. ├── agent-plugin-eval/
  571. │ ├── SKILL.md
  572. │ ├── agents/ # default evaluation agent
  573. │ ├── references/ # spec checklist, 18-criterion rubric, output template
  574. │ └── scripts/ # score.py + inspect_plugin.py (static audit)
  575. ├── agent-ready-cloudflare/
  576. │ ├── README.md # human-readable documentation with examples
  577. │ ├── SKILL.md # main skill (API docs, operational flow, prompt templates)
  578. │ └── */SKILL.md # 25 implementation sub-skills (robots-txt, mcp-server-card, etc.)
  579. ├── auth-md/
  580. │ ├── SKILL.md
  581. │ └── references/ # protocol template, validation rules, metadata schema, example, implementation guide
  582. ├── pstack-skill/
  583. │ ├── README.md # human-readable guide: install, use cases, model roles
  584. │ ├── SKILL.md # the orchestrator (playbook router, principles index, autonomy rules)
  585. │ ├── UPSTREAM_COMMIT # reviewed upstream reference
  586. │ ├── playbooks/ # 23 step-by-step workflows copied verbatim onto todolists
  587. │ ├── references/ # 24 principles, 31 bundled procedures, adapters and upstream review
  588. │ └── scripts/ # statechart compiler, plan validator, log, audit and upstream checker
  589. ├── okf-open-knowledge-format/
  590. │ ├── SKILL.md
  591. │ ├── references/ # OKF spec, bundle anatomy, enrichment rules
  592. │ └── scripts/ # validate.sh — bundle validator
  593. ├── ralph-loop-kiro-specs/
  594. │ ├── SKILL.md
  595. │ ├── scripts/ # bash loop runner script
  596. │ └── references/ # Ralph agent prompt template
  597. ├── loop-architect/
  598. │ ├── SKILL.md # loop design coach (adapted from Looper by ksimback)
  599. │ ├── scripts/ # compiler and model detection
  600. │ ├── templates/ # portable Python runner
  601. │ ├── references/ # rubrics (goal, verification, council, control)
  602. │ ├── schemas/ # loop.yaml JSON schema
  603. │ └── examples/ # ai-workflow-mapping example
  604. ├── motion-ad/
  605. │ ├── SKILL.md
  606. │ ├── assets/ # template.html — finished 15s 4:5 ad, one CONFIG object
  607. │ ├── references/ # template anatomy: render contract, CONFIG, geometry, recipes
  608. │ └── scripts/ # render.cjs (GSAP→MP4), fetch-images.cjs, contact-sheet.py
  609. └── resume-ats-beater/
  610. ├── SKILL.md
  611. └── references/ # diagnostic templates, output structure
  612. ```
  613. ## Author
  614. Created by [ft.ia.br](https://ft.ia.br)
  615. ## References
  616. - [Lessons from building Claude Code: How we use skills](https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills) — Anthropic's skill category framework (9 types)
  617. - [Best practices for skill creators](https://agentskills.io/skill-creation/best-practices) — Writing guidance from the Agent Skills spec
  618. - [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills) — Eval-driven iteration with test cases and benchmarks
  619. ## License
  620. Apache 2.0 — see [LICENSE](LICENSE) for details — **except where a skill directory contains its own LICENSE file, which governs that skill instead.**
  621. ⚠️ **Exception:** [`skills/revenue-centric-design/`](skills/revenue-centric-design/LICENSE) is **source-available, not open-source**. The underlying ideas are the intellectual property of Richard ([@richardrx](https://x.com/richardrx)), used with permission, and **may not be used for gambling, betting, or casino products**. That restriction survives any copy or derivative and is not waived by this repository's Apache 2.0 license.
skills/loop-architect/scripts/looper.py · Bundled script · 822 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """Loop-architect helper CLI.
  3. This script belongs to the scaffolding side of loop-architect. It may detect
  4. installed CLIs, register invocation metadata, compile loop.yaml to
  5. loop.resolved.json, and render LOOP.md. It must not invoke model CLIs to do
  6. loop work.
  7. Based on Looper by Kevin Simback (https://github.com/ksimback/looper), MIT License.
  8. Adapted for Kiro CLI by ft.ia.br.
  9. """
  10. from __future__ import annotations
  11. import argparse
  12. import datetime as _dt
  13. import json
  14. import os
  15. from pathlib import Path
  16. import shlex
  17. import shutil
  18. import subprocess
  19. import sys
  20. from typing import Any
  21. DEFAULT_REDACTIONS = [".env", ".env.*", "secrets/**", "**/*.key"]
  22. REGISTRY_PATH = Path.home() / ".loop-architect" / "models.json"
  23. MODEL_PROBES: dict[str, dict[str, Any]] = {
  24. "kiro": {
  25. "invoke": ["kiro-cli", "chat", "--trust-all-tools", "-p"],
  26. "probe": ["kiro-cli", "--version"],
  27. "local": False,
  28. "install": "Install Kiro CLI: https://kiro.dev/downloads/",
  29. "capabilities": ["headless", "goal", "subagent", "review_loop"],
  30. },
  31. "claude": {
  32. "invoke": ["claude", "-p"],
  33. "probe": ["claude", "--version"],
  34. "local": False,
  35. "install": "Install and authenticate the Claude CLI.",
  36. "capabilities": ["headless", "goal"],
  37. },
  38. "codex": {
  39. "invoke": ["codex", "exec"],
  40. "probe": ["codex", "--version"],
  41. "local": False,
  42. "install": "Install and authenticate the Codex CLI.",
  43. "capabilities": ["headless", "goal"],
  44. },
  45. "gemini": {
  46. "invoke": ["gemini", "-p"],
  47. "probe": ["gemini", "--version"],
  48. "local": False,
  49. "install": "Install and authenticate the Gemini CLI.",
  50. "capabilities": ["headless"],
  51. },
  52. "llm": {
  53. "invoke": ["llm"],
  54. "probe": ["llm", "--version"],
  55. "local": False,
  56. "install": "Install llm and configure a model/provider.",
  57. "capabilities": ["headless"],
  58. },
  59. "ollama": {
  60. "invoke": ["ollama", "run"],
  61. "probe": ["ollama", "--version"],
  62. "local": True,
  63. "install": "Install Ollama and pull a local model.",
  64. "capabilities": ["headless"],
  65. },
  66. }
  67. class LooperError(RuntimeError):
  68. pass
  69. def load_yaml(path: Path) -> dict[str, Any]:
  70. try:
  71. import yaml # type: ignore
  72. except ImportError as exc:
  73. raise LooperError(
  74. "PyYAML is required to compile loop.yaml. Install with: python -m pip install PyYAML"
  75. ) from exc
  76. try:
  77. with path.open("r", encoding="utf-8") as fh:
  78. data = yaml.safe_load(fh)
  79. except OSError as exc:
  80. raise LooperError(f"Could not read {path}: {exc}") from exc
  81. except yaml.YAMLError as exc:
  82. raise LooperError(f"Could not parse YAML in {path}: {exc}") from exc
  83. if not isinstance(data, dict):
  84. raise LooperError(f"{path} must contain a YAML mapping at the top level")
  85. return data
  86. def load_json(path: Path) -> dict[str, Any]:
  87. with path.open("r", encoding="utf-8") as fh:
  88. data = json.load(fh)
  89. if not isinstance(data, dict):
  90. raise LooperError(f"{path} must contain a JSON object")
  91. return data
  92. def write_json(path: Path, data: Any) -> None:
  93. path.parent.mkdir(parents=True, exist_ok=True)
  94. path.write_text(json.dumps(to_jsonable(data), indent=2, sort_keys=True) + "\n", encoding="utf-8")
  95. def to_jsonable(value: Any) -> Any:
  96. if isinstance(value, dict):
  97. return {str(key): to_jsonable(item) for key, item in value.items()}
  98. if isinstance(value, list):
  99. return [to_jsonable(item) for item in value]
  100. if isinstance(value, (_dt.date, _dt.datetime)):
  101. return value.isoformat()
  102. return value
  103. def read_registry(path: Path = REGISTRY_PATH) -> dict[str, Any]:
  104. if not path.exists():
  105. return {}
  106. with path.open("r", encoding="utf-8") as fh:
  107. data = json.load(fh)
  108. if not isinstance(data, dict):
  109. raise LooperError(f"Registry {path} must contain a JSON object")
  110. return data
  111. def write_registry(data: dict[str, Any], path: Path = REGISTRY_PATH) -> None:
  112. path.parent.mkdir(parents=True, exist_ok=True)
  113. write_json(path, data)
  114. def run_probe(argv: list[str], timeout_sec: int = 5) -> tuple[bool, str]:
  115. probe_argv = list(argv)
  116. if os.name == "nt":
  117. resolved = shutil.which(argv[0])
  118. if resolved and Path(resolved).suffix.lower() in {".cmd", ".bat"}:
  119. probe_argv = ["cmd", "/d", "/c", *argv]
  120. try:
  121. completed = subprocess.run(
  122. probe_argv,
  123. stdin=subprocess.DEVNULL,
  124. stdout=subprocess.PIPE,
  125. stderr=subprocess.PIPE,
  126. text=True,
  127. timeout=timeout_sec,
  128. check=False,
  129. )
  130. except (OSError, subprocess.TimeoutExpired) as exc:
  131. return False, str(exc)
  132. output = (completed.stdout or completed.stderr or "").strip()
  133. return completed.returncode == 0, output.splitlines()[0] if output else ""
  134. def detect_models() -> dict[str, Any]:
  135. registry: dict[str, Any] = {}
  136. for model_id, meta in MODEL_PROBES.items():
  137. cli = meta["invoke"][0]
  138. path = shutil.which(cli)
  139. available = path is not None
  140. authed = False
  141. version = ""
  142. if available:
  143. authed, version = run_probe(meta["probe"])
  144. registry[model_id] = {
  145. "cli": cli,
  146. "path": path,
  147. "invoke": meta["invoke"],
  148. "available": available,
  149. "authed": authed,
  150. "local": meta["local"],
  151. "probe": meta["probe"],
  152. "version": version,
  153. "install": meta["install"],
  154. "capabilities": meta.get("capabilities", []),
  155. }
  156. return registry
  157. def normalize_argv(value: Any, field: str) -> list[str]:
  158. if isinstance(value, list) and all(isinstance(item, str) for item in value):
  159. return value
  160. if isinstance(value, str):
  161. return shlex.split(value, posix=os.name != "nt")
  162. raise LooperError(f"{field} must be an argv array or string")
  163. def criteria_by_id(spec: dict[str, Any]) -> dict[str, dict[str, Any]]:
  164. criteria = spec.get("goal", {}).get("verification", [])
  165. if not isinstance(criteria, list):
  166. raise LooperError("goal.verification must be a list")
  167. result: dict[str, dict[str, Any]] = {}
  168. for item in criteria:
  169. if not isinstance(item, dict):
  170. raise LooperError("Each verification criterion must be an object")
  171. cid = item.get("id")
  172. ctype = item.get("type")
  173. if not isinstance(cid, str) or not cid:
  174. raise LooperError("Each verification criterion needs a non-empty id")
  175. if cid in result:
  176. raise LooperError(f"Duplicate verification criterion id: {cid}")
  177. if ctype not in {"programmatic", "judge", "human"}:
  178. raise LooperError(f"Criterion {cid} has invalid type: {ctype}")
  179. if ctype == "programmatic":
  180. item["check"] = normalize_argv(item.get("check"), f"criterion {cid}.check")
  181. if item.get("expect") not in {"exit_zero", "exit_nonzero", "stdout_contains"}:
  182. raise LooperError(
  183. f"Criterion {cid}.expect must be exit_zero, exit_nonzero, or stdout_contains"
  184. )
  185. if item.get("expect") == "stdout_contains" and not isinstance(item.get("contains"), str):
  186. raise LooperError(f"Criterion {cid} with stdout_contains needs contains")
  187. elif ctype == "judge" and not isinstance(item.get("rubric"), str):
  188. raise LooperError(f"Criterion {cid} needs a judge rubric")
  189. elif ctype == "human" and not isinstance(item.get("prompt"), str):
  190. raise LooperError(f"Criterion {cid} needs a human prompt")
  191. result[cid] = item
  192. return result
  193. def validate_member(member: dict[str, Any]) -> None:
  194. mid = member.get("id")
  195. role = member.get("role")
  196. if not isinstance(mid, str) or not mid:
  197. raise LooperError("Each council member needs a non-empty id")
  198. if role not in {"reviewer", "judge"}:
  199. raise LooperError(f"Council member {mid} role must be reviewer or judge")
  200. member["invoke"] = normalize_argv(member.get("invoke"), f"council.{mid}.invoke")
  201. timeout = member.get("timeout_sec", 600)
  202. if not isinstance(timeout, int) or timeout <= 0:
  203. raise LooperError(f"Council member {mid}.timeout_sec must be a positive integer")
  204. member.setdefault("scope", ["plan", "delivery"])
  205. member.setdefault("local", member.get("cli") == "ollama")
  206. def validate_gate(
  207. name: str,
  208. gate: dict[str, Any],
  209. criteria: dict[str, dict[str, Any]],
  210. members: dict[str, dict[str, Any]],
  211. ) -> None:
  212. if not isinstance(gate, dict):
  213. raise LooperError(f"{name} must be an object")
  214. policy = gate.get("verdict_policy")
  215. if policy not in {"revise_until_clean", "fixed_passes"}:
  216. raise LooperError(f"{name}.verdict_policy must be revise_until_clean or fixed_passes")
  217. max_revisions = gate.get("max_revisions", 1)
  218. if not isinstance(max_revisions, int) or max_revisions < 0:
  219. raise LooperError(f"{name}.max_revisions must be a non-negative integer")
  220. for cid in gate.get("criteria", []):
  221. if cid not in criteria:
  222. raise LooperError(f"{name} references unknown criterion: {cid}")
  223. for mid in gate.get("members", []):
  224. if mid not in members:
  225. raise LooperError(f"{name} references unknown council member: {mid}")
  226. if policy == "revise_until_clean":
  227. source = gate.get("verdict_source")
  228. if source == "human":
  229. return
  230. if source not in members:
  231. raise LooperError(f"{name}.verdict_source must be a judge member or human")
  232. if members[source].get("role") != "judge":
  233. raise LooperError(f"{name}.verdict_source must name a judge, not a reviewer")
  234. def normalize_spec(spec: dict[str, Any], source_path: Path) -> dict[str, Any]:
  235. if spec.get("version") != 1:
  236. raise LooperError("Only loop.yaml version: 1 is supported")
  237. goal = spec.get("goal")
  238. if not isinstance(goal, dict):
  239. raise LooperError("goal must be an object")
  240. if not isinstance(goal.get("statement"), str) or not goal["statement"].strip():
  241. raise LooperError("goal.statement is required")
  242. if not isinstance(goal.get("definition_of_done"), str) or not goal["definition_of_done"].strip():
  243. raise LooperError("goal.definition_of_done is required")
  244. for index, source in enumerate(goal.get("context_sources", [])):
  245. if not isinstance(source, dict):
  246. raise LooperError("goal.context_sources entries must be objects")
  247. if "cmd" in source:
  248. source["cmd"] = normalize_argv(source["cmd"], f"context_sources[{index}].cmd")
  249. criteria = criteria_by_id(spec)
  250. host = spec.get("host")
  251. if not isinstance(host, dict):
  252. raise LooperError("host must be an object")
  253. host["invoke"] = normalize_argv(host.get("invoke"), "host.invoke")
  254. host.setdefault("timeout_sec", 600)
  255. if not isinstance(host["timeout_sec"], int) or host["timeout_sec"] <= 0:
  256. raise LooperError("host.timeout_sec must be a positive integer")
  257. council_list = spec.get("council", [])
  258. if not isinstance(council_list, list):
  259. raise LooperError("council must be a list")
  260. for member in council_list:
  261. if not isinstance(member, dict):
  262. raise LooperError("council entries must be objects")
  263. validate_member(member)
  264. members = {member["id"]: member for member in council_list}
  265. gates = spec.get("gates")
  266. if not isinstance(gates, dict):
  267. raise LooperError("gates must be an object")
  268. for gate_name in ("plan_gate", "delivery_gate"):
  269. validate_gate(gate_name, gates.get(gate_name), criteria, members)
  270. control = spec.get("loop_control")
  271. if not isinstance(control, dict):
  272. raise LooperError("loop_control must be an object")
  273. max_iterations = control.get("max_iterations")
  274. if not isinstance(max_iterations, int) or max_iterations <= 0:
  275. raise LooperError("loop_control.max_iterations must be a positive integer")
  276. budget = control.setdefault("budget", {})
  277. if not isinstance(budget, dict):
  278. raise LooperError("loop_control.budget must be an object")
  279. if "wall_clock_min" not in budget:
  280. budget["wall_clock_min"] = 30
  281. no_progress = control.setdefault(
  282. "no_progress",
  283. {
  284. "max_stalled_iterations": 2,
  285. "signals": [
  286. "same blocking issue repeats",
  287. "delivery artifact has no material change",
  288. "verifier output is unchanged",
  289. ],
  290. "action": "stop",
  291. },
  292. )
  293. if not isinstance(no_progress, dict):
  294. raise LooperError("loop_control.no_progress must be an object")
  295. stalled = no_progress.setdefault("max_stalled_iterations", 2)
  296. if not isinstance(stalled, int) or stalled <= 0:
  297. raise LooperError("loop_control.no_progress.max_stalled_iterations must be a positive integer")
  298. signals = no_progress.setdefault("signals", ["same blocking issue repeats"])
  299. if not isinstance(signals, list) or not all(isinstance(item, str) for item in signals):
  300. raise LooperError("loop_control.no_progress.signals must be a list of strings")
  301. action = no_progress.setdefault("action", "stop")
  302. if action not in {"stop", "human_checkpoint"}:
  303. raise LooperError("loop_control.no_progress.action must be stop or human_checkpoint")
  304. execution = spec.setdefault(
  305. "execution",
  306. {
  307. "mode": "in_session",
  308. "isolation": "current_workspace",
  309. "side_effects": {"requires_approval": True, "duplicate_action_check": True},
  310. },
  311. )
  312. if not isinstance(execution, dict):
  313. raise LooperError("execution must be an object")
  314. execution.setdefault("mode", "in_session")
  315. execution.setdefault("isolation", "current_workspace")
  316. if execution["mode"] not in {"in_session", "external_runner", "orchestrated"}:
  317. raise LooperError("execution.mode must be in_session, external_runner, or orchestrated")
  318. if execution["isolation"] not in {"current_workspace", "branch", "worktree", "sandbox"}:
  319. raise LooperError("execution.isolation must be current_workspace, branch, worktree, or sandbox")
  320. side_effects = execution.setdefault("side_effects", {})
  321. if not isinstance(side_effects, dict):
  322. raise LooperError("execution.side_effects must be an object")
  323. side_effects.setdefault("requires_approval", True)
  324. side_effects.setdefault("duplicate_action_check", True)
  325. observability = spec.setdefault(
  326. "observability",
  327. {"state_file": "state.json", "run_log": "run-log.md", "checkpoint_granularity": "gate"},
  328. )
  329. if not isinstance(observability, dict):
  330. raise LooperError("observability must be an object")
  331. observability.setdefault("state_file", "state.json")
  332. observability.setdefault("run_log", "run-log.md")
  333. observability.setdefault("checkpoint_granularity", "gate")
  334. if not isinstance(observability["state_file"], str) or not observability["state_file"]:
  335. raise LooperError("observability.state_file must be a non-empty string")
  336. if not isinstance(observability["run_log"], str) or not observability["run_log"]:
  337. raise LooperError("observability.run_log must be a non-empty string")
  338. if observability["checkpoint_granularity"] not in {"gate", "step"}:
  339. raise LooperError("observability.checkpoint_granularity must be gate or step")
  340. workspace = spec.setdefault("workspace", {})
  341. if not isinstance(workspace, dict):
  342. raise LooperError("workspace must be an object")
  343. workspace.setdefault("dir", "./loop-workspace")
  344. layout = workspace.setdefault("layout", ["plan.md", "delivery-{n}.md", "review-{n}.md", "state.json", "run-log.md"])
  345. if not isinstance(layout, list) or not all(isinstance(item, str) for item in layout):
  346. raise LooperError("workspace.layout must be a list of strings")
  347. for required_file in (observability["state_file"], observability["run_log"]):
  348. if required_file not in layout:
  349. layout.append(required_file)
  350. privacy = spec.setdefault("privacy", {})
  351. if not isinstance(privacy, dict):
  352. raise LooperError("privacy must be an object")
  353. egress = privacy.setdefault("egress", [])
  354. if not isinstance(egress, list):
  355. raise LooperError("privacy.egress must be a list")
  356. for entry in egress:
  357. if not isinstance(entry, dict):
  358. raise LooperError("privacy.egress entries must be objects")
  359. entry.setdefault("redact", DEFAULT_REDACTIONS)
  360. entry.setdefault("consent", "required")
  361. resolved = {
  362. "$schema": "https://github.com/ksimback/looper/schema/loop.resolved.v1.json",
  363. "compiled_at": _dt.datetime.now(_dt.UTC).replace(microsecond=0).isoformat(),
  364. "source": str(source_path),
  365. **spec,
  366. "criteria_by_id": criteria,
  367. "council_by_id": members,
  368. }
  369. return to_jsonable(resolved)
  370. def clip(text: Any, width: int) -> str:
  371. value = str(text or "")
  372. return value if len(value) <= width else value[: width - 1] + "~"
  373. def ascii_box(*rows: str, width: int = 30) -> list[str]:
  374. border = "+" + "-" * (width + 2) + "+"
  375. body = [f"| {clip(row, width):<{width}} |" for row in rows if row is not None]
  376. return [border, *body, border]
  377. def render_ascii_diagram(resolved: dict[str, Any]) -> str:
  378. gates = resolved.get("gates", {})
  379. control = resolved.get("loop_control", {})
  380. observability = resolved.get("observability", {})
  381. plan_gate = gates.get("plan_gate", {})
  382. delivery_gate = gates.get("delivery_gate", {})
  383. plan_revisions = plan_gate.get("max_revisions", 0)
  384. delivery_revisions = delivery_gate.get("max_revisions", 0)
  385. plan_source = plan_gate.get("verdict_source", "human")
  386. delivery_source = delivery_gate.get("verdict_source", "human")
  387. no_progress = control.get("no_progress", {})
  388. stalled = no_progress.get("max_stalled_iterations", 2)
  389. budget = control.get("budget", {})
  390. budget_bits = []
  391. if budget.get("wall_clock_min") is not None:
  392. budget_bits.append(f"{budget.get('wall_clock_min')}m")
  393. if budget.get("usd") is not None:
  394. budget_bits.append(f"${budget.get('usd')}")
  395. if budget.get("tokens") is not None:
  396. budget_bits.append(f"{budget.get('tokens')} tokens")
  397. budget_text = ", ".join(budget_bits) or "configured caps"
  398. lines: list[str] = []
  399. lines.extend(ascii_box("1. Goal + context", "read sources"))
  400. lines.extend([" |", " v"])
  401. lines.extend(ascii_box("2. Draft plan.md", f"state -> {observability.get('state_file', 'state.json')}"))
  402. lines.extend([" |", " v"])
  403. lines.extend(ascii_box("3. Plan gate", f"verdict: {plan_source}"))
  404. lines.extend([f" | needs work -> revise <= {plan_revisions} -> step 2", " | pass", " v"])
  405. lines.extend(ascii_box("4. Write delivery-N.md", f"log -> {observability.get('run_log', 'run-log.md')}"))
  406. lines.extend([" |", " v"])
  407. lines.extend(ascii_box("5. Delivery gate", f"verdict: {delivery_source}"))
  408. lines.extend([f" | needs work -> revise <= {delivery_revisions} -> step 4", " | pass", " v"])
  409. lines.extend(ascii_box("6. Final output", "all gates clean"))
  410. lines.extend(
  411. [
  412. "",
  413. f"Stops: pass gates | max {control.get('max_iterations')} iterations | "
  414. f"no progress x{stalled} | budget {budget_text}",
  415. ]
  416. )
  417. return "\n".join(lines)
  418. def render_loop(resolved: dict[str, Any]) -> str:
  419. meta = resolved.get("meta", {})
  420. goal = resolved.get("goal", {})
  421. gates = resolved.get("gates", {})
  422. control = resolved.get("loop_control", {})
  423. execution = resolved.get("execution", {})
  424. observability = resolved.get("observability", {})
  425. title = meta.get("name") or "Looper Generated Loop"
  426. criteria = goal.get("verification", [])
  427. council = resolved.get("council", [])
  428. lines = [
  429. f"# {title}",
  430. "",
  431. meta.get("description", "").strip(),
  432. "",
  433. "## Goal",
  434. "",
  435. goal.get("statement", "").strip(),
  436. "",
  437. "## Definition of Done",
  438. "",
  439. goal.get("definition_of_done", "").strip(),
  440. "",
  441. "## Verification",
  442. "",
  443. ]
  444. for item in criteria:
  445. lines.append(f"- `{item['id']}` ({item['type']})")
  446. lines.extend(["", "## Council", ""])
  447. if council:
  448. for member in council:
  449. lines.append(
  450. f"- `{member['id']}`: {member.get('role')} via {member.get('cli')} "
  451. f"({member.get('model', 'default')})"
  452. )
  453. else:
  454. lines.append("- No council members configured.")
  455. lines.extend(
  456. [
  457. "",
  458. "## Gates",
  459. "",
  460. f"- Plan gate: {gates.get('plan_gate', {}).get('verdict_policy')}",
  461. f"- Delivery gate: {gates.get('delivery_gate', {}).get('verdict_policy')}",
  462. "",
  463. "## Loop Control",
  464. "",
  465. f"- Max iterations: {control.get('max_iterations')}",
  466. f"- Budget: `{json.dumps(control.get('budget', {}), sort_keys=True)}`",
  467. f"- No-progress: `{json.dumps(control.get('no_progress', {}), sort_keys=True)}`",
  468. "",
  469. "## Execution Boundary",
  470. "",
  471. f"- Mode: `{execution.get('mode', 'in_session')}`",
  472. f"- Isolation: `{execution.get('isolation', 'current_workspace')}`",
  473. f"- Side effects: `{json.dumps(execution.get('side_effects', {}), sort_keys=True)}`",
  474. "",
  475. "## Observability",
  476. "",
  477. f"- State file: `{observability.get('state_file', 'state.json')}`",
  478. f"- Run log: `{observability.get('run_log', 'run-log.md')}`",
  479. f"- Checkpoint granularity: `{observability.get('checkpoint_granularity', 'gate')}`",
  480. "",
  481. "## Flow Preview",
  482. "",
  483. "```text",
  484. render_ascii_diagram(resolved),
  485. "```",
  486. "",
  487. ]
  488. )
  489. return "\n".join(line for line in lines if line is not None)
  490. def render_session_prompt(resolved: dict[str, Any]) -> str:
  491. meta = resolved.get("meta", {})
  492. goal = resolved.get("goal", {})
  493. gates = resolved.get("gates", {})
  494. control = resolved.get("loop_control", {})
  495. workspace = resolved.get("workspace", {})
  496. execution = resolved.get("execution", {})
  497. observability = resolved.get("observability", {})
  498. criteria = goal.get("verification", [])
  499. council = resolved.get("council", [])
  500. title = meta.get("name") or "Looper Generated Loop"
  501. lines = [
  502. f"# Run `{title}` In This Session",
  503. "",
  504. "Use this prompt when the user wants to run the Looper-designed loop in the current LLM session.",
  505. "This is the default/easy execution path. The Python runner is the advanced path for running later or outside the session.",
  506. "",
  507. "## Operator Instructions",
  508. "",
  509. "You are executing a Looper-designed loop in this current session.",
  510. "Follow the resolved spec below, write handoff files into the workspace, and enforce the caps manually.",
  511. "Do not use `run-loop.py` unless the user explicitly asks for the advanced external runner.",
  512. "",
  513. "1. Create the workspace directory if it does not exist.",
  514. "2. Read the context sources before drafting the plan.",
  515. "3. Draft `plan.md` in the workspace.",
  516. "4. Run the plan gate. Apply programmatic checks when available. For judge criteria, use the configured judge only after consent for any non-local egress; otherwise ask the user to approve a human/current-session substitute.",
  517. "5. Revise until the gate passes or `max_revisions` is reached.",
  518. "6. Produce `delivery-N.md` in the workspace.",
  519. "7. Run the delivery gate after each delivery.",
  520. "8. Stop when all delivery criteria pass, a cap is reached, or the user stops the loop.",
  521. "9. Keep `state.json` current with status, iteration, last gate, consent, and blockers.",
  522. "10. Append a compact entry to `run-log.md` after every context read, model call, check, gate verdict, revision, blocker, and stop decision.",
  523. "11. Compare each blocker against the previous blocker. If the same blocker repeats for the configured no-progress window, stop or ask for the configured human checkpoint instead of revising again.",
  524. "12. Treat token and USD budgets as operator limits in this session: if exact accounting is unavailable, stop and ask before continuing when the loop appears likely to exceed them.",
  525. "",
  526. "## Files",
  527. "",
  528. f"- Source spec: `{Path(resolved.get('source', 'loop.yaml')).name}`",
  529. "- Human summary: `LOOP.md`",
  530. "- Resolved spec: `loop.resolved.json`",
  531. f"- Workspace: `{workspace.get('dir', './loop-workspace')}`",
  532. f"- State file: `{observability.get('state_file', 'state.json')}`",
  533. f"- Run log: `{observability.get('run_log', 'run-log.md')}`",
  534. "",
  535. "## Goal",
  536. "",
  537. goal.get("statement", "").strip(),
  538. "",
  539. "## Definition Of Done",
  540. "",
  541. goal.get("definition_of_done", "").strip(),
  542. "",
  543. "## Context Sources",
  544. "",
  545. ]
  546. context_sources = goal.get("context_sources", [])
  547. if context_sources:
  548. for source in context_sources:
  549. if "file" in source:
  550. lines.append(f"- Read file `{source['file']}`")
  551. elif "cmd" in source:
  552. lines.append(f"- Run command `{json.dumps(source['cmd'])}`")
  553. else:
  554. lines.append("- No context sources configured.")
  555. lines.extend(["", "## Verification Criteria", ""])
  556. for item in criteria:
  557. if item["type"] == "programmatic":
  558. lines.append(
  559. f"- `{item['id']}` programmatic: run `{json.dumps(item['check'])}` and expect `{item['expect']}`"
  560. )
  561. elif item["type"] == "judge":
  562. lines.append(f"- `{item['id']}` judge rubric: {item['rubric']}")
  563. elif item["type"] == "human":
  564. lines.append(f"- `{item['id']}` human signoff: {item['prompt']}")
  565. lines.extend(["", "## Council", ""])
  566. if council:
  567. for member in council:
  568. locality = "local" if member.get("local") else "non-local"
  569. lines.append(
  570. f"- `{member['id']}` {member.get('role')} via `{json.dumps(member.get('invoke', []))}` "
  571. f"({locality}; timeout {member.get('timeout_sec', 600)}s)"
  572. )
  573. else:
  574. lines.append("- No council members configured.")
  575. lines.extend(["", "## Gates", ""])
  576. for gate_name in ("plan_gate", "delivery_gate"):
  577. gate = gates.get(gate_name, {})
  578. lines.extend(
  579. [
  580. f"### {gate_name}",
  581. "",
  582. f"- When: `{gate.get('when')}`",
  583. f"- Policy: `{gate.get('verdict_policy')}`",
  584. f"- Verdict source: `{gate.get('verdict_source', 'none')}`",
  585. f"- Criteria: `{', '.join(gate.get('criteria', []))}`",
  586. f"- Max revisions: `{gate.get('max_revisions')}`",
  587. "",
  588. ]
  589. )
  590. lines.extend(
  591. [
  592. "## Loop Control",
  593. "",
  594. f"- Max iterations: `{control.get('max_iterations')}`",
  595. f"- Budget: `{json.dumps(control.get('budget', {}), sort_keys=True)}`",
  596. f"- No-progress: `{json.dumps(control.get('no_progress', {}), sort_keys=True)}`",
  597. f"- Human checkpoints: `{', '.join(control.get('human_checkpoints', [])) or 'none'}`",
  598. "- Stop conditions:",
  599. ]
  600. )
  601. for condition in control.get("stop_conditions", []):
  602. lines.append(f" - {condition}")
  603. lines.extend(
  604. [
  605. "",
  606. "## Execution Boundary",
  607. "",
  608. f"- Mode: `{execution.get('mode', 'in_session')}`",
  609. f"- Isolation: `{execution.get('isolation', 'current_workspace')}`",
  610. f"- Side effects: `{json.dumps(execution.get('side_effects', {}), sort_keys=True)}`",
  611. "",
  612. "If the loop needs scheduled runs, child-agent lifecycle management, concurrency control, or restart-safe step retries, stop and tell the user this Looper spec should be handed to a durable orchestrator.",
  613. "",
  614. "## Observability",
  615. "",
  616. f"- State file: `{observability.get('state_file', 'state.json')}`",
  617. f"- Run log: `{observability.get('run_log', 'run-log.md')}`",
  618. f"- Checkpoint granularity: `{observability.get('checkpoint_granularity', 'gate')}`",
  619. "",
  620. "Use `state.json` for the latest resumable status and `run-log.md` for the append-only history of what happened.",
  621. ]
  622. )
  623. lines.extend(["", "## Privacy", ""])
  624. egress = resolved.get("privacy", {}).get("egress", [])
  625. if egress:
  626. for entry in egress:
  627. lines.append(
  628. f"- Before sending `{', '.join(entry.get('sends', []))}` to `{entry.get('to')}`, "
  629. f"confirm consent and apply redactions `{', '.join(entry.get('redact', []))}`."
  630. )
  631. else:
  632. lines.append("- No cross-vendor egress configured.")
  633. lines.extend(
  634. [
  635. "",
  636. "## Start Now",
  637. "",
  638. "If the user asked to run now, begin at step 1 under Operator Instructions and keep going until a stop condition is reached.",
  639. "",
  640. ]
  641. )
  642. return "\n".join(lines)
  643. def cmd_detect(args: argparse.Namespace) -> int:
  644. registry = detect_models()
  645. if args.write:
  646. existing = read_registry(args.registry)
  647. existing.update(registry)
  648. write_registry(existing, args.registry)
  649. print(json.dumps(registry, indent=2, sort_keys=True))
  650. return 0
  651. def cmd_register(args: argparse.Namespace) -> int:
  652. if not args.invoke:
  653. raise LooperError("--invoke needs at least one command token")
  654. registry = read_registry(args.registry)
  655. registry[args.model_id] = {
  656. "cli": args.invoke[0],
  657. "invoke": args.invoke,
  658. "available": shutil.which(args.invoke[0]) is not None,
  659. "authed": args.authed,
  660. "local": args.local,
  661. "model": args.model,
  662. "notes": args.notes or "",
  663. }
  664. write_registry(registry, args.registry)
  665. print(f"Registered {args.model_id} in {args.registry}")
  666. return 0
  667. def cmd_compile(args: argparse.Namespace) -> int:
  668. source = args.loop_yaml.resolve()
  669. spec = load_yaml(source)
  670. resolved = normalize_spec(spec, source)
  671. out = args.out or source.with_name("loop.resolved.json")
  672. write_json(out, resolved)
  673. if args.render:
  674. args.render.parent.mkdir(parents=True, exist_ok=True)
  675. args.render.write_text(render_loop(resolved), encoding="utf-8")
  676. if args.session_prompt:
  677. args.session_prompt.parent.mkdir(parents=True, exist_ok=True)
  678. args.session_prompt.write_text(render_session_prompt(resolved), encoding="utf-8")
  679. print(f"Wrote {out}")
  680. if args.render:
  681. print(f"Wrote {args.render}")
  682. if args.session_prompt:
  683. print(f"Wrote {args.session_prompt}")
  684. return 0
  685. def cmd_session_prompt(args: argparse.Namespace) -> int:
  686. resolved = load_json(args.resolved_json)
  687. prompt = render_session_prompt(resolved)
  688. if args.out:
  689. args.out.parent.mkdir(parents=True, exist_ok=True)
  690. args.out.write_text(prompt, encoding="utf-8")
  691. print(f"Wrote {args.out}")
  692. else:
  693. print(prompt)
  694. return 0
  695. def build_parser() -> argparse.ArgumentParser:
  696. parser = argparse.ArgumentParser(prog="looper", description="Looper scaffolding helpers")
  697. sub = parser.add_subparsers(dest="command", required=True)
  698. detect = sub.add_parser("detect-models", help="Detect model CLIs and print registry JSON")
  699. detect.add_argument("--write", action="store_true", help="Merge results into the model registry")
  700. detect.add_argument("--registry", type=Path, default=REGISTRY_PATH)
  701. detect.set_defaults(func=cmd_detect)
  702. register = sub.add_parser("register-model", help="Register custom model CLI invocation metadata")
  703. register.add_argument("model_id")
  704. register.add_argument("--invoke", nargs="+", required=True)
  705. register.add_argument("--model", default="")
  706. register.add_argument("--local", action="store_true")
  707. register.add_argument("--authed", action="store_true")
  708. register.add_argument("--notes", default="")
  709. register.add_argument("--registry", type=Path, default=REGISTRY_PATH)
  710. register.set_defaults(func=cmd_register)
  711. compile_cmd = sub.add_parser("compile", help="Compile loop.yaml to loop.resolved.json")
  712. compile_cmd.add_argument("loop_yaml", type=Path)
  713. compile_cmd.add_argument("--out", type=Path)
  714. compile_cmd.add_argument("--render", type=Path)
  715. compile_cmd.add_argument("--session-prompt", type=Path)
  716. compile_cmd.set_defaults(func=cmd_compile)
  717. session_prompt = sub.add_parser(
  718. "session-prompt", help="Render the in-session execution prompt from loop.resolved.json"
  719. )
  720. session_prompt.add_argument("resolved_json", type=Path)
  721. session_prompt.add_argument("--out", type=Path)
  722. session_prompt.set_defaults(func=cmd_session_prompt)
  723. return parser
  724. def main(argv: list[str] | None = None) -> int:
  725. parser = build_parser()
  726. args = parser.parse_args(argv)
  727. try:
  728. return int(args.func(args))
  729. except LooperError as exc:
  730. print(f"looper: error: {exc}", file=sys.stderr)
  731. return 2
  732. if __name__ == "__main__":
  733. raise SystemExit(main())
skills/ralph-loop-kiro-specs/scripts/ralph-loop-kiro-specs-script.sh · Bundled script · 128 lines · 1 finding marked
  1. #!/bin/bash
  2. set -e
  3. # Ralph Loop for Kiro Specs — Runner Script
  4. # Based on https://github.com/mreferre/ralph-loop-kiro-specs
  5. # Licensed under Apache License 2.0
  6. #
  7. # Usage: ./ralph-loop-kiro-specs-script.sh <max_iterations> <specs_name>
  8. # ── Color & style codes ──
  9. RED='\033[1;31m'
  10. GREEN='\033[1;32m'
  11. YELLOW='\033[1;33m'
  12. BLUE='\033[1;34m'
  13. CYAN='\033[1;36m'
  14. MAGENTA='\033[1;35m'
  15. BOLD='\033[1m'
  16. DIM='\033[2m'
  17. NC='\033[0m' # No Color
  18. MAX_ITERATIONS=${1:-10}
  19. SPECS_NAME=${2:-}
  20. if [ -z "$SPECS_NAME" ]; then
  21. echo -e "${RED}❌ Usage: $0 <max_iterations> <specs_name>${NC}" >&2
  22. exit 1
  23. fi
  24. # Validate MAX_ITERATIONS is a positive integer
  25. if ! [[ "$MAX_ITERATIONS" =~ ^[1-9][0-9]*$ ]]; then
  26. echo -e "${RED}❌ Error: <max_iterations> must be a positive integer, got '${BOLD}$MAX_ITERATIONS${RED}'${NC}" >&2
  27. exit 1
  28. fi
  29. # Validate SPECS_NAME is a non-empty string (no whitespace-only)
  30. if ! [[ "$SPECS_NAME" =~ [^[:space:]] ]]; then
  31. echo -e "${RED}❌ Error: <specs_name> must be a non-empty string${NC}" >&2
  32. exit 1
  33. fi
  34. SCRIPT_DIR="$(cd "$(dirname \
  35. "${BASH_SOURCE[0]}")" && pwd)"
  36. # Set the specs directory path based on the provided specs name
  37. SPECS_DIR="$SCRIPT_DIR/.kiro/specs/$SPECS_NAME"
  38. # Check if the specs directory exists, exit with error if not found
  39. if [ ! -d "$SPECS_DIR" ]; then
  40. echo -e "${RED}❌ Error: No specs named '${BOLD}$SPECS_NAME${RED}' found in this project${NC}" >&2
  41. exit 1
  42. fi
  43. # Initialize progress log file if it doesn't exist
  44. if [ ! -f "$SPECS_DIR/progress.md" ]; then
  45. echo "# Progress Log for spec: $SPECS_NAME" \
  46. > "$SPECS_DIR/progress.md"
  47. echo -e "${DIM}📝 Created progress.md${NC}"
  48. fi
  49. # Initialize time log file if it doesn't exist
  50. TIME_LOG="$SPECS_DIR/specs_time.md"
  51. if [ ! -f "$TIME_LOG" ]; then
  52. echo "# Time Log for spec: $SPECS_NAME" > "$TIME_LOG"
  53. echo -e "${DIM}📝 Created specs_time.md${NC}"
  54. fi
  55. # Load the prompt template and substitute the specs name placeholder
  56. PROMPT=$(sed "s/SPECS_NAME/$SPECS_NAME/g" \
  57. "$SCRIPT_DIR/ralph-loop-kiro-specs-prompt.md")
  58. echo ""
  59. echo -e "${MAGENTA}══════════════════════════════════════${NC}"
  60. echo -e " 🚀 ${BOLD}Starting Ralph${NC}"
  61. echo -e " ${DIM}spec:${NC} ${CYAN}$SPECS_NAME${NC}"
  62. echo -e " ${DIM}iterations:${NC} ${CYAN}$MAX_ITERATIONS${NC}"
  63. echo -e "${MAGENTA}══════════════════════════════════════${NC}"
  64. echo ""
  65. # Ask user for iteration mode
  66. read -r -p "$(echo -e "${YELLOW}🔄 Iterate automatically through tasks? (y/n):${NC} ")" AUTO_MODE
  67. case "$AUTO_MODE" in
  68. [yY]|[yY][eE][sS])
  69. AUTO_MODE=true
  70. echo -e " ${GREEN}✔ Auto-pilot enabled${NC}"
  71. ;;
  72. *)
  73. AUTO_MODE=false
  74. echo -e " ${BLUE}✔ Manual mode — you'll confirm each iteration${NC}"
  75. ;;
  76. esac
  77. echo ""
  78. echo -e "${CYAN}─── 📋 Prompt ───────────────────────────${NC}"
  79. echo "$PROMPT"
  80. echo -e "${CYAN}──────────────────────────────────────────${NC}"
  81. echo ""
  82. read -r -p "$(echo -e "${YELLOW}👀 Review the prompt above. Press Enter to launch the Ralph loop...${NC} ")"
  83. echo ""
  84. for i in $(seq 1 $MAX_ITERATIONS); do
  85. echo -e "${BLUE}═══════════════════════════════════════${NC}"
  86. echo -e " 🔁 ${BOLD}Iteration ${CYAN}$i${NC}${BOLD} / ${DIM}$MAX_ITERATIONS${NC}"
  87. echo -e "${BLUE}═══════════════════════════════════════${NC}"
  88. OUTPUT=$(echo "$PROMPT" \
  89. | kiro-cli chat --trust-all-tools --no-interactive 2>&1 \
  90. | tee /dev/stderr) || true
  91. if echo "$OUTPUT" | \
  92. grep -q "<promise>COMPLETE</promise>"
  93. then
  94. echo ""
  95. echo -e "${GREEN}══════════════════════════════════════${NC}"
  96. echo -e " ✅ ${BOLD}All tasks complete!${NC}"
  97. echo -e "${GREEN}══════════════════════════════════════${NC}"
  98. exit 0
  99. fi
  100. if [ "$AUTO_MODE" = false ]; then
  101. echo ""
  102. read -r -p "$(echo -e "${YELLOW}⏸️ Iteration $i done. Press Enter to continue...${NC} ")"
  103. fi
  104. done
  105. echo ""
  106. echo -e "${RED}══════════════════════════════════════${NC}"
  107. echo -e " ⚠️ ${BOLD}Max iterations reached${NC} ${DIM}($MAX_ITERATIONS)${NC}"
  108. echo -e "${RED}══════════════════════════════════════${NC}"
  109. exit 1

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.