okf-open-knowledge-format

🇧🇷 Versao em Portugues do Brasil

审核状态：已审核Quality 72Security 52

复制安装命令

用 Codex 或 Claude 安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它先审查 Skill 页面再帮你安装。

复制前请先查看来源、License 和安全提示。

项目 README

来源文件：README.md

抓取于 2026年9月13日

🇧🇷 Versao em Portugues do Brasil

🧠 AI Agent Skills — Open Source Collection for Claude Code, Cursor, Kiro & OpenCode

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.

Agent Skills 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.

Available Skills

💡 Startup Idea · `data-fetching-and-analysis`

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.

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".

📄 View full documentation

🔍 GEO Optimization (Generative Engine Optimization) · `code-quality-and-review`

Optimizes digital content and marketing strategies for Generative Engines (LLMs, AI agents) to maximize citations in AI responses.

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.

Improvements in v1.1 (Mar 2026):

Moved Guiding Principles and case study context to references/guiding-principles.md
Fixed second-person language to imperative form throughout
Added explicit default action (Full GEO Audit) when no specific request is made
Converted Edge Cases section into a structured Quality Checklist with checkboxes
Description optimized to be more concise and actionable (Mar 8)

📄 View full documentation

📰 Substack Expert · `library-and-api-reference`

Substack platform expert. Guides post formatting, SEO optimization (titles, slugs, meta descriptions), native engagement strategies (Notes, Chat), and conversion to paid subscriptions.

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.

Improvements in v1.1 (Mar 2026):

Removed duplicate Overview section and stray Portuguese artifact/orphaned code fence
Moved formatting tips to references/formatting-best-practices.md
Moved Input/Output Examples to references/seo-output-example.md
Added Parameters table with defaults for topic, goal, and language
Added explicit Clarify Scope step for ambiguous requests
Added Quality Checklist with 8 pre-delivery verification points

📄 View full documentation

☁️ Pier Cloud API · `library-and-api-reference`

Complete guide to consuming the Pier Cloud (Lighthouse) API with authentication, context management, workspaces, and data views. Note: The documentation for this skill is in Portuguese, but it can be used in any language.

When to use: authenticate with Pier Cloud, list available contexts (AWS, etc), manage workspaces, access cost analysis views, run FinOps scripts.

Improvements in v1.1 (Mar 2026):

Rewrote description to third-person trigger format
Removed verbatim Overview section that duplicated the frontmatter description
Fixed broken and incomplete Prerequisites section
Converted second-person language to imperative form throughout
Cleaned up workflow links to properly defer to references/REFERENCE.md
Added Quality Checklist

📄 View full documentation

🎨 Ultimate Design System Master · `code-scaffolding-and-templates`

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.

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.

Improvements in v2.1 (Mar 2026):

Rewrote description to third-person trigger format
Moved 18-question Briefing Questionnaire to references/briefing-questionnaire.md
Added Quality Checklist with 5 concrete verification conditions
Removed intro sentence that duplicated frontmatter description

Improvements in v2.2 (Mar 8, 2026):

Description rewritten with user-spoken trigger phrases for better skill activation
License Apache 2.0 added to metadata
Full compliance with Official Anthropic Guide for Agent Skills achieved

📄 View full documentation

🗂️ Front-End Checklist (moved)

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.

👉 Install directly from: https://github.com/thedaviddias/Front-End-Checklist/tree/main/skills
npx skills add frontendchecklist/skills

🚀 Coolify Operator · `ci-cd-and-deployment`

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.

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.

Key features:

Application creation (5 methods): public repo, GitHub App, deploy key, Dockerfile, Docker image
Full lifecycle management: start, stop, restart, delete, move between environments
Environment variables: list, create, update, delete, sync from .env files
Storage management: persistent volumes, file mounts, directory mounts
Database backups: scheduled backups with S3/local retention, trigger on-demand
Deploy module: deploy by UUID, name, or batch multiple resources at once
GitHub Apps: create integrations, list accessible repos and branches
Services (one-click): WordPress, Ghost, n8n, and 50+ more with sub-resource management
Infrastructure: destinations, cloud tokens (Hetzner/DO/Vultr), private keys, tags

New in v2.0 (Aug 15, 2026):

Complete rewrite covering 100% of official Coolify CLI commands
Added app create (5 variants: public, github, deploy-key, dockerfile, dockerimage)
Added app storage, app deployments, app previews, app tags
Added database create/backup/storage/env/tags with full backup management
Added service create --list-types, service application, service database sub-resources
Added deploy uuid/name/batch module with deploy list/get/cancel
Added github list/get/create/update/delete/repos/branches for GitHub Apps
Added projects, resources, tags, destinations, cloud-token, private-key
Added LLM/AI Agent integration section with llms.txt references
Updated to match latest CLI documentation

📄 View full documentation

📄 Resume ATS Beater + LinkedIn Optimizer · `code-scaffolding-and-templates`

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.

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.

Improvements in v2.0 (Jun 2026):

Added modo_linkedin (full profile audit with scoring) and modo_unificado (CV + LinkedIn with consistency check)
LinkedIn audit: headline format enforcement (Position | Areas | Tools·), about structure, experience bullets, language, skills, featured, SSI
Punitive scoring system: 100 - (critical×15 + warning×6 + info×2)
SSI analysis with 4 pillars, classification by tier, and actionable tips
Fix prompts per finding (standalone prompts for any LLM)
Mega-prompt for full profile rewrite by LLM
18 career presets across tech, data, marketing, finance, engineering, legal, sales, HR, product
Integration with humanizar skill (scoped to About/Summary sections)
3 new reference files: auditoria-linkedin.md, ssi.md, presets-formatos.md

📄 View full documentation

🤖 Agent Ready — Cloudflare Scanner · `product-verification`

Audits any website for AI agent readiness using the Cloudflare isitagentready.com scanner. Scans 18 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 20 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.

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.

📄 View full documentation

✅ DESIGN.md Validator · `product-verification`

Validates DESIGN.md files against the official Google design.md specification 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.

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.

📄 View full documentation

🔁 Ralph Loop for Kiro Specs · `code-scaffolding-and-templates`

Automated iterative agent runner for spec-based development in Kiro. 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 by mreferre.

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.

📄 View full documentation

🏗️ Loop Architect — Agent Loop Design Coach · `code-scaffolding-and-templates`

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 by Kevin Simback.

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.

📄 View full documentation

👑 Pstack Skills — 23 Playbooks for Claude Code, Cursor & OpenCode · `code-quality-and-review`

Self-contained port of Lauren Tan's pstack (poteto-mode) — 23 playbooks, 21 procedures, 21 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.

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.

📄 View full documentation

✍️ Humanizar — AI Text Humanizer for Brazilian Portuguese · `code-quality-and-review`

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.

Origin story: I started from the English humanizer skill by @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 directory and the concept of semantic ablation (The Register, 2026), and built a skill that doesn't just remove bad patterns — it restores the entropy that AI strips away.

Why it's better for PT-BR than the original:

55+ patterns vs 25 (including 10 that only exist in Brazilian Portuguese)
Semantic entropy restoration with explicit alerts (not just removal)
6 voice presets calibrated for Brazilian contexts (crônica, journalistic, academic, corporate, social media, WhatsApp)
Examples are culturally Brazilian, not translations from English
Preserves naturalized foreign words (feedback, deploy, churn) — fighting linguistic purism is itself a humanization signal
Uses the Brazilian crônica literary tradition as the gold standard for natural writing

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".

Improvements in v1.2 (Jun 2026):

Added automatic document type detection with fallback (Step 0.5) — auto-selects the best voice preset
Added post-rewrite scoring with 5 weighted dimensions (Step 5.5) — quantifiable quality gate
Added iterative loop with strategy fallback — retries with different approaches when score < 60
Loop protocol compatible with external orchestrator skills (ralph-wiggum, goal)
Inspired by humanize-it by @smallnest

New in v1.3 (Jul 2026):

Added 📋 Português Simplificado voice profile — accessible writing inspired by PorSimples (NILC/USP) and Brazil's Lei 15.263/2025 (National Plain Language Policy)
7 syntactic simplification operations based on PorSimples research (sentence splitting, passive→active, SVO reordering, discourse marker substitution, apposition removal, lexical simplification, subject explicitation)
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)
Integration with TRAVA FACTUAL: explicit rules for when NOT to simplify (modality, causality, exceptions)
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

New in v1.5 (Sep 2026):

3 new rapid-consumption profiles inspired by the 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 (MIT)
New reference file references/padroes-consumo-rapido.md with formatting rules, cut rules, TRAVA FACTUAL integration, and verification checklist
Updated Step 1 (detection) with 3 new automatic signals
Updated Step 3 (references) with the new rapid-consumption reference
Updated Step 5 (voice application) with Apply/Avoid for all 3 profiles
Updated Step 6 (false-positive guard) with 6 specific exceptions: bold lead-ins, arrows, short sentences, checklists, long lists, and single-line paragraphs
Added brevity verification in Step 7 (5 items): propositions preserved, warnings not removed, scope not generalized, modality preserved, exact numbers kept
TRAVA FACTUAL reinforced: brevity compresses form, not content — never omit warnings, numbers, or scope conditions
Now 13 voice profiles (was 10)

New in v1.4 (Aug 2026):

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
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
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
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
Em-dash recalibrated from weight 1 to weight 2, with a mandatory sweep for —, – and -- before delivery, plus explicit exceptions (fiction dialogue, author sample)
Regression suite extended to T8 (human-mark preservation and fabricated-source handling)

Credits and sources for humanizar:

The false-positive guard, the human-marks list, the from-scratch writing mode and five patterns were incorporated from PedroLLou/humanizador (MIT), the Brazilian Portuguese version of blader/humanizer (MIT), which in turn derives from Wikipedia: Signs of AI writing, maintained by WikiProject AI Cleanup.

Portuguese-language sources behind those adaptations:

Marcelo Sabbatini, "Texto chocho: como identificar a escrita da IA?", IAEdPraxis — source for crucial and mergulhar as PT-BR markers, generic adjectives, the serial comma and the period-inside-quotes convention
Marina Semensato, "Como saber se um texto foi feito por inteligência artificial?", Exame — connective overuse, conclusions that only restate the text, forced triads and "não é X, é Y"
Inteligência artificial na Wikimedia, Portuguese Wikipedia — em-dash overuse, "além disso" overuse, promotional material, curly quotes and non-existent references
Pew Research Center, "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

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.

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).

📄 View full documentation

🌐 Human-AI — AI Text Humanizer for English · `code-quality-and-review`

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.

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 (10.6K stars, 29 patterns), brandonwise/humanizer (560-term vocab filter, statistical signals), and 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.

Why it's different from the existing humanizer skills:

43 patterns (including P31-P43 emerging patterns from 2026 community research)
Research-backed metrics: TTR human 0.553 vs AI 0.455 (SSRN), burstiness +0.70 vs 0.00 (GPTZero)
scripts/measure.py — deterministic TTR/burstiness/entropy calculation (zero dependencies)
7 voice presets calibrated for English contexts (essay, journalistic, academic, corporate, social, casual, legal, instructional)
Anti-synonym-swap enforcement: Step 2 requires full sentence restructuring, not word replacement
7 documented gotchas from real-world humanizer skill failures
Iterative loop with scoring (0-100) and strategy fallback table
Composes with external loop skills (ralph-wiggum, goal)

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.

📄 View full documentation

🔐 auth.md — Agent Authentication Protocol · `library-and-api-reference`

Generates, validates, and explains auth.md 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.

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.

📄 View full documentation | 🌐 auth-md.com

📦 OKF — Open Knowledge Format · `library-and-api-reference`

Create, validate, and enrich Open Knowledge Format 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.

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.

📄 View full documentation | 🌐 okf.md

🌐 Website Spec (moved)

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.

👉 Use the official skill: https://specification.website/.well-known/agent-skills/specification-website/SKILL.md

MCP endpoint: https://mcp.specification.website/mcp

🔒 LGPD Check

Migrated → This skill moved to github.com/lgpd-app/skills

Audits websites for compliance with Brazil's LGPD (Lei 13.709/2018).

🔒 LGPD.md

Migrated → This skill moved to github.com/lgpd-app/skills

Generates and validates lgpd.md files — the LGPD compliance declaration standard.

📊 Skill Evaluation · `code-quality-and-review`

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.

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". 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.

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.

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)

5 bonus patterns (measured, not scored): Validation loops · Output templates · Procedures over declarations · Defaults over menus · Trace-checkable steering

How it differs from agentskills.io evals and skill-creator benchmark:

	This skill	agentskills.io evals	skill-creator benchmark
Evaluates	Skill structure quality + trigger empirically	Skill output quality	Output + regression + obsolescence
Method	Static inspection + sub-agent trigger eval	Run test cases + grade	A/B blind comparison + multi-agent
When	Is it well-built? Does it trigger correctly?	Does it work?	Did it regress? Still needed?
Output	Scorecard + grade A-F + trigger hit/leak rates	pass_rate, tokens, time	benchmark.json + comparator verdict
Platform	Any agent	Any agent	Claude Code only (plugin)

Use in sequence: skill-evaluation (design review + trigger testing) → evals (functional validation) → benchmark (ongoing monitoring).

📄 View full documentation

🧹 Slop Eval — Design Slop Evaluator · `code-quality-and-review`

Objectively evaluates a UI/web design against the pols.dev anti-slop design law: 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.

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.

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.

New in v1.1.0 (Aug 2026):

Section Ledger: per-section verdicts (CLEAN/SUSPICIOUS/INFLATED/CRITICAL) with tell density bands and action recommendations
Design Contexts: context-aware evaluation for landing pages, SaaS dashboards, editorial, and e-commerce — adjusts priority tells and tolerances per design type
Exclusion System: formalized // BRIEF:, // DESIGN DECISION:, // CONTEXT:, // PREMIUM PAIR: tags for documenting excluded tells with audit trail
Tracking Mode: temporal evolution analysis with tells resolved/introduced, regressions, velocity metrics, and recommendations for next iteration
Adding Soul Guide: prescription-oriented guide for injecting personality into each axis — not just "remove tell X" but "replace with premium alternative Y"
Expanded Quality Checklist: 25+ checks across 6 phases (pre-sweep, during-sweep, exclusion, post-sweep, report, self-audit) including portability and defense tests

Companions: method inspired by skill-evaluation; for text (not design), human-ai and humanizar do the de-slopping.

📄 View full documentation

🛡️ Security Specialist · `runbooks`

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.

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.

Key features:

Input-driven SOP: path only → SAST + dev DAST; path + URL → SAST + dev + prod; URL only → DAST
12 steering workflows: full-scan, diff-review, pentest, hunting, threat-model, attack-paths, discovery, triage, remediation, tracking, validation, reporting
6-phase pipeline (full-scan): Recon → Hunt → Validate → Report → Schema → Verify — with parallel agents and adversarial validation
9 attack classes: Injection, Access Control, Resource/File, Cryptography, Business Logic, Feature Abuse, Chained Attacks, Wildcard, Obvious Things
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
Adversarial validation: separate agents try to DISPROVE findings (5 gates: exploitation, impact, baseline, mitigation, parser/runtime)
Structured JSON output: findings.json validated against JSON schema with trace (entrypoint→propagation→sink), conditions, execution, confidence
Schema validator: zero-dependency Node.js script (validate-findings.cjs) for CI integration
Multi-run additive coverage: each run targets gaps from prior runs; single run finds ~50% of total vulnerabilities
5 utility scripts: SQLite scan DB, file ranker, report finalizer, pentest automation, schema validator
Pentest tool cascade: nmap → python-nmap → socket scan; nikto → wapiti3 → header checks; gobuster → dirsearch → urllib brute
Three-layer correlation: source finding → dev exploit → prod confirmation
Dynamic baseline calibration: compares patterns against industry-standard comparable applications

Architecture:

security-specialist/
├── SKILL.md              (router + core principles + anti-patterns)
├── steering/             (12 workflow docs including hunting methodology)
├── scripts/              (5 tools: Python + Node.js validator)
└── references/           (5 spec docs: finding format, report format, severity policy, artifacts, report-schema.json)

Improvements in v2.0 (Jun 2026):

Added 6-phase audit pipeline with parallel agents (inspired by Cloudflare security-audit-skill)
Added steering/hunting.md with 9 attack classes and 12-angle hunting methodology
Added adversarial validation (Phase 3) and independent verification (Phase 6)
Added references/report-schema.json for structured findings with trace, conditions, execution, confidence
Added scripts/validate-findings.cjs zero-dependency JSON schema validator
Added multi-run additive coverage strategy
Added 10 anti-patterns to avoid in security audits
Added dynamic baseline calibration to severity policy
Enhanced finding format: simple (SQLite) + structured (JSON pipeline) dual format

📄 View full documentation

🚀 Astro Sites Manager · `ci-cd-and-deployment`

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.

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.

Key features:

MCP Astro Docs integration (real-time docs access)
10 reference files covering migration, validation, testing, deployment, Starlight, and more
Coolify-specific deployment guide with 17-project battle-tested patterns
Feature detection: v7 features activate only when available (safe on v6)

📄 View full documentation

🔌 Agent Plugin Eval · `product-verification`

Audits, scores, and compares repositories containing portable Agent Plugins against the official Agent Plugins specification. 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.

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.

Key features:

Static-only audit (never executes plugin code, MCP servers, or scripts)
18-criterion rubric across 4 axes: Portable conformance, Components & integration, Safety & resilience, Product quality
Conformance gates: PASS (no cap), PARTIAL (capped at 59), FAIL (capped at 39)
Deterministic scoring via scripts/score.py
Comparison mode for evaluating two plugins side by side
Client-agnostic: evaluates against portable spec, not Codex/Claude/Cursor-specific features

📄 View full documentation

💰 Revenue-Centric Design · `runbooks`

Playbook of 101 evidence-backed principles for designing SaaS and startup products that convert, retain, and monetize — landing pages & CRO, 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.

Origin story: Richard (@richardrx, "Design for startups" — ex-Volkswagen, PayPal, IBM) published these principles as 101 posts in Portuguese on X. Helio Costa 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). This repository hosts an evolved derivative of that work.

Evolution measured with skill-evaluation: the as-downloaded skill scored 60/100 (B, borderline C); one improvement pass later, 73/100 (B):

Criterion	before	after
Scripts & libraries	0	75
Gotchas section	35	88
Coherent scope	55	72
Progressive disclosure	78	90
Description for trigger	78	90
Repo footprint	39 MB	176 KB

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.

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.

⚠️ 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.

📄 View full documentation

Skills revised in March 2026 following the Anthropic standard for Agent Skills structure and quality. Source: Improving Skill Creator: Test, Measure and Refine Agent Skills

Installation

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

Via Skills.sh

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

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

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

Clone this repository:

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

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/
cp -r skills/astro-sites-manager .cursor/skills/
cp -r skills/agent-plugin-eval .cursor/skills/

# Example for Claude Code
cp -r skills/geo-optimization .claude/skills/
cp -r skills/substack-expert .claude/skills/
cp -r skills/pier-cloud .claude/skills/
cp -r skills/ultimate-design-system-master .claude/skills/
cp -r skills/resume-ats-beater .claude/skills/
cp -r skills/coolify-operator .claude/skills/
cp -r skills/agent-ready-cloudflare .claude/skills/
cp -r skills/ralph-loop-kiro-specs .claude/skills/
cp -r skills/loop-architect .claude/skills/
cp -r skills/humanizar .claude/skills/
cp -r skills/auth-md .claude/skills/
cp -r skills/astro-sites-manager .claude/skills/
cp -r skills/agent-plugin-eval .claude/skills/

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

The Agent Skills format is universal and works with any compatible agent. See the official specification for details.

Repository Structure

skills/
├── startup-idea/
│   ├── SKILL.md
│   └── evals/    # 3 lenses: Graham, Koe, Godin
├── revenue-centric-design/
│   ├── SKILL.md
│   ├── references/  # 101 principles + audit output template
│   └── scripts/     # revenue math: A/B sample size, churn to LTV, CAC
├── geo-optimization/
│   ├── SKILL.md
│   └── references/  # guiding principles and case studies
├── substack-expert/
│   ├── SKILL.md
│   └── references/  # formatting best practices, SEO output example
├── humanizar/
│   ├── SKILL.md
│   └── references/  # 55+ AI patterns specific to Brazilian Portuguese (7 files)
├── human-ai/
│   ├── SKILL.md
│   ├── references/  # 43 EN patterns, empirical baselines
│   └── scripts/     # measure.py — deterministic metrics
├── pier-cloud/
│   ├── SKILL.md
│   ├── scripts/     # Python scripts for API consumption
│   └── references/  # API reference, troubleshooting guide
├── coolify-operator/
│   ├── SKILL.md
│   └── evals/    # 8 test scenarios
├── astro-sites-manager/
│   ├── SKILL.md
│   └── references/  # Astro v7 migration, routing, deploy targets
├── security-specialist/
│   ├── SKILL.md
│   ├── steering/    # 12 workflow docs including hunting methodology
│   ├── scripts/     # 5 tools: Python + Node.js validator
│   └── references/  # 5 spec docs: finding/report format, severity policy
├── ultimate-design-system-master/
│   ├── SKILL.md
│   └── references/  # briefing questionnaire, 10 specialized prompt files
├── design-md-validator/
│   ├── SKILL.md
│   └── references/  # Google DESIGN.md spec, lint rules, export formats
├── skill-evaluation/
│   ├── SKILL.md
│   ├── references/  # 18 criteria across 4 axes, scorecard template
│   └── scripts/     # trigger eval runner
├── slop-eval/
│   ├── SKILL.md
│   ├── references/  # 8 axes of the anti-slop law
│   └── scripts/     # Slop Index calculator
├── agent-plugin-eval/
│   ├── SKILL.md
│   ├── agents/      # default evaluation agent
│   ├── references/  # spec checklist, 18-criterion rubric, output template
│   └── scripts/     # score.py + inspect_plugin.py (static audit)
├── agent-ready-cloudflare/
│   ├── README.md   # human-readable documentation with examples
│   ├── SKILL.md    # main skill (API docs, operational flow, prompt templates)
│   └── */SKILL.md  # 20 implementation sub-skills (robots-txt, mcp-server-card, etc.)
├── auth-md/
│   ├── SKILL.md
│   └── references/  # protocol template, validation rules, metadata schema, example, implementation guide
├── pstack-skill/
│   ├── README.md        # human-readable guide: install, use cases, model roles
│   ├── SKILL.md         # the orchestrator (playbook router, principles index, autonomy rules)
│   ├── UPSTREAM_COMMIT  # reviewed upstream reference
│   ├── playbooks/       # 23 step-by-step workflows copied verbatim onto todolists
│   ├── references/      # 21 principles, 21 bundled procedures, plan + bot-review triage
│   └── scripts/         # decision-log helper, worktree audit
├── okf-open-knowledge-format/
│   ├── SKILL.md
│   ├── references/  # OKF spec, bundle anatomy, enrichment rules
│   └── scripts/     # validate.sh — bundle validator
├── ralph-loop-kiro-specs/
│   ├── SKILL.md
│   ├── scripts/     # bash loop runner script
│   └── references/  # Ralph agent prompt template
├── loop-architect/
│   ├── SKILL.md     # loop design coach (adapted from Looper by ksimback)
│   ├── scripts/     # compiler and model detection
│   ├── templates/   # portable Python runner
│   ├── references/  # rubrics (goal, verification, council, control)
│   ├── schemas/     # loop.yaml JSON schema
│   └── examples/    # ai-workflow-mapping example
└── resume-ats-beater/
    ├── SKILL.md
    └── references/  # diagnostic templates, output structure

Author

Created by ft.ia.br

References

Lessons from building Claude Code: How we use skills — Anthropic's skill category framework (9 types)
Best practices for skill creators — Writing guidance from the Agent Skills spec
Evaluating skill output quality — Eval-driven iteration with test cases and benchmarks

License

Apache 2.0 — see LICENSE for details — except where a skill directory contains its own LICENSE file, which governs that skill instead.

⚠️ Exception: skills/revenue-centric-design/ is source-available, not open-source. The underlying ideas are the intellectual property of Richard (@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.

其他

高风险

来源需自行核对维护者身份。
包含脚本或命令调用，安装前请复核。
可能需要外部 token、网络权限或第三方服务。
存在潜在风险命令，请谨慎安装。
扫描发现：4 条。

Codex — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/fabricioctelles/skills.git
将 "skills/okf-open-knowledge-format" 文件夹复制到 Codex 的 skills 目录中。
重启 Codex 让新的 skill 生效。

Codex — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Codex 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Codex 让新的 skill 生效。

Claude Code — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/fabricioctelles/skills.git
将 "skills/okf-open-knowledge-format" 文件夹复制到 Claude Code 的 skills 目录中。
重启 Claude Code 让新的 skill 生效。

Claude Code — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Claude Code 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Claude Code 让新的 skill 生效。

Cursor — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/fabricioctelles/skills.git
将 "skills/okf-open-knowledge-format" 文件夹复制到 Cursor 的 skills 目录中。
重启 Cursor 让新的 skill 生效。

Cursor — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Cursor 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Cursor 让新的 skill 生效。

GitHub Copilot — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/fabricioctelles/skills.git
将 "skills/okf-open-knowledge-format" 文件夹复制到 GitHub Copilot 的 skills 目录中。
重启 GitHub Copilot 让新的 skill 生效。

GitHub Copilot — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 GitHub Copilot 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 GitHub Copilot 让新的 skill 生效。

Windsurf — Git Clone 安装

安装前请先查看来源仓库和风险报告。
克隆仓库：git clone https://github.com/fabricioctelles/skills.git
将 "skills/okf-open-knowledge-format" 文件夹复制到 Windsurf 的 skills 目录中。
重启 Windsurf 让新的 skill 生效。

Windsurf — 手动复制安装

安装前请先查看来源仓库和风险报告。
从源仓库下载 SKILL.md 及相关文件。
在 Windsurf 的 skills 目录中创建新文件夹。
将所有 skill 文件复制到新文件夹中。
重启 Windsurf 让新的 skill 生效。

查看 SKILL.md 原文

name: okf-open-knowledge-format
description: >
  Create, validate, and enrich Open Knowledge Format (OKF) bundles — the open
  spec for representing organizational knowledge as markdown files with YAML
  frontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format',
  'knowledge bundle', 'OKF bundle', 'create a knowledge base for agents',
  'validate OKF', 'convert to OKF', 'enrich knowledge docs', 'agent-readable
  knowledge', 'LLM wiki', 'knowledge catalog', 'kcmd', or wants to structure
  knowledge as markdown files for AI agent consumption. Also use when the user
  has a directory of markdown files and wants to make them interoperable or
  conformant with the OKF standard. Even for simple requests like 'make this
  folder OKF conformant' — the skill has critical structural rules the agent
  needs.
metadata:
  author: ft.ia.br
  version: "2.0"
  date: 2026-08-25
  repository: https://github.com/fabricioctelles/skills
  license: Apache-2.0
  category: library-and-api-reference
  upstream: https://github.com/GoogleCloudPlatform/open-knowledge-format

Open Knowledge Format (OKF)

OKF is a vendor-neutral, open spec (v0.2, released by Google Cloud) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can cat a file, you can read OKF.

It formalizes the "LLM Wiki" pattern (Karpathy's gist) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.

v0.2 adds: provenance tracking (sources), trust signals (generated, verified), lifecycle management (status, stale_after), and Attested Computations — a new concept type for sanctioned, verifiable calculations.

For the full spec, see:

references/spec-v02.md — Current version (v0.2)
references/spec-v01.md — Legacy version (v0.1)

Design Principles

Minimally opinionated — Only type is required. The spec defines interoperability surface, not content model.
Producer/consumer independence — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
Format, not platform — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.
Trust is first-class — v0.2 makes provenance, verification, and freshness queryable from frontmatter.

Key Terminology

Term	Definition
Bundle	A directory tree of `.md` files. The unit of distribution (git repo, tarball, or subdirectory).
Concept	One markdown file = one unit of knowledge (table, metric, playbook, API, etc.)
Concept ID	File path within the bundle, minus `.md` suffix. Example: `tables/users.md` → ID `tables/users`
Frontmatter	YAML block between `---` delimiters at file top.
Body	Everything after the frontmatter. Standard markdown.
Link	Standard markdown link expressing a relationship between concepts.
Source	A material a concept derives from, recorded in the `sources` frontmatter field.
Provenance	The set of sources a concept derives from.
Actor	Identity string: `<producer>/<version>` for agents, `human:<id>` for people, `process:<id>` for automation.
Trust tier	Level derived from `verified`: unverified, machine-confirmed, or human-reviewed.
Attested Computation	A concept (`type: Attested Computation`) carrying a sanctioned way to compute a value.

Quick Reference — Frontmatter Fields

Core Fields (all concepts)

Field	Required?	Description
`type`	YES	Kind of concept (free-form string, e.g. `BigQuery Table`, `Metric`, `Playbook`, `Attested Computation`)
`title`	Recommended	Human-readable display name
`description`	Recommended	One-sentence summary
`resource`	Recommended	URI identifying the underlying asset (omit for abstract concepts)
`tags`	Optional	YAML list for cross-cutting categorization

Trust & Lifecycle Fields (v0.2)

Field	Description
`generated`	`{ by: <actor>, at: <ISO8601> }` — Who/what created this content and when
`verified`	List of `{ by: <actor>, at: <ISO8601> }` — Who confirmed correctness
`status`	`draft` \| `stable` \| `deprecated` — Default: `stable`
`stale_after`	ISO 8601 datetime — Content is stale on/after this instant

Provenance Fields (v0.2)

Field	Description
`sources`	List of source entries (see below)
`usage_window`	`{ from, to }` — Time range for `usage_count` signals

Each sources entry:

resource (REQUIRED): URL, bundle-relative path, or scope descriptor
id: Stable key for footnote attribution
title: Human-readable label
author: Actor who produced the source
usage_count: How often exercised (liveness signal)
last_modified: When the source last changed

Attested Computation Fields (v0.2)

For concepts with type: Attested Computation:

Field	Description
`runtime`	REQUIRED. How to run it: `bigquery`, `postgres`, `dbt`, `python`, `Looker`
`parameters`	List of `{ name, type, required }` — Typed holes the agent fills
`computation`	Path to computation file (if not inline in body)
`executor`	`{ resource, receipt: [...] }` — How to run and what evidence to capture
`attester`	`{ resource }` — Deterministic code that verifies the receipt

Reserved Filenames

File	Purpose	Has frontmatter?
`index.md`	Directory listing for progressive disclosure	NO*
`log.md`	Change history, newest first	NO

*Exception: bundle-root index.md MAY have frontmatter with okf_version: "0.2".

Conventional Body Headings

Heading	When to use
`# Schema`	Data assets — describe columns/fields
`# Examples`	Show concrete usage (code blocks, queries)
`# Computation`	Attested Computation — the sanctioned code/query

Actor Convention

Fields that record identity (generated.by, verified[].by, sources[].author) use:

<producer>/<version> for agents: reference_agent/gemini-2.5-pro
human:<id> for people: human:ahormati
process:<id> for automation: process:finance-nightly

Trust tiers are derived from the human: prefix — human-verified > machine-confirmed > unverified.

Trust Tiers

Consumers derive trust from the verified field:

Condition	Trust Tier
No `verified` key	Unverified
`verified` by non-`human:` actors only	Machine-confirmed
`verified` by a `human:<id>` actor	Human-reviewed

Trust tiers are advisory signals, not access control.

Create a Bundle

When the user wants to create an OKF bundle from scratch:

1. Determine scope and structure

Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.) Organize into a directory tree that makes sense for the domain.

2. Create concept documents

Each concept = one .md file. Minimal conformant example:

---
type: Metric
---

# Monthly Recurring Revenue (MRR)

Sum of all active subscriptions normalized to a monthly amount.

Full v0.2 example with provenance and trust:

---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas, kpi]
status: stable
generated: { by: human:ftelles, at: 2026-08-25T10:00:00Z }
verified: { by: human:finance-lead, at: 2026-08-25T14:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: stripe-docs
    resource: https://stripe.com/docs/billing/subscriptions
    title: Stripe Subscription Billing
    author: team:stripe-docs
    last_modified: 2026-06-01T00:00:00Z
---

# Monthly Recurring Revenue (MRR)

## Definition

Sum of all active subscriptions normalized to a monthly amount.[^stripe-docs]
Excludes one-time fees and overages.

## Formula

`MRR = Σ(active_subscription_monthly_value)`

## Related

- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12

[^stripe-docs]: Stripe Subscription Billing

For more examples across domains, see references/examples.md.

3. Cross-link concepts

Use standard markdown links. Two forms:

Absolute (bundle-relative, starts with /): [customers](/tables/customers.md) — preferred (stable when files move)
Relative: [churn](./churn.md)

Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.

4. Add provenance with footnotes (v0.2)

When claims reference external sources, use sources in frontmatter and footnotes in body:

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema

The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: GA4 BigQuery Export schema

5. Generate index.md

Place in any directory for progressive disclosure. No frontmatter. Format:

# Metrics

- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score

Entries should include the description from the linked concept's frontmatter.

6. Generate log.md (optional)

Chronological change history, newest first, ISO 8601 date headings:

# Update Log

## 2026-08-25
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.

## 2026-08-20
- **Initialization**: Bundle created.

7. Declare version (optional)

Bundle-root index.md may include frontmatter declaring the spec version:

---
okf_version: "0.2"
---

# My Knowledge Bundle

- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs

8. Distribution

A bundle can be distributed as:

A git repository (recommended — history, attribution, diffs)
A tarball or zip archive
A subdirectory within a larger repository

9. Verify conformance

Three rules — all must pass:

Every non-reserved .md file has parseable YAML frontmatter
Every frontmatter has a non-empty type field
Reserved files (index.md, log.md) follow their defined structure when present

Create an Attested Computation (v0.2)

Attested Computations are concepts that carry not just what a value means but a sanctioned way to compute it. Use them when you need verifiable, reproducible calculations.

When to use

Financial metrics where compliance requires audit trails
KPIs that must be computed consistently across reports
Any calculation where "did the sanctioned thing run" matters

Structure

---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

The computation binds only the declared `parameters`, per the recognition
policy.[^rev-policy]

[^rev-policy]: Revenue recognition policy

Key rules

Agent fills parameters only — The agent supplies values for declared parameters, never edits the computation itself
Computation can be inline or external — Use # Computation heading for inline, or computation: field for external file
Executor produces receipt — Evidence the attester inspects
Attester is deterministic — No LLM, just code that verifies the receipt

Linking to computations

Other concepts link to Attested Computations:

---
type: Metric
title: Revenue
---

# Definition

Recognized revenue for a fiscal year, computed by 
[the revenue computation](../computations/revenue.md).

Validate a Bundle

Preferred: okflint (when available)

okflint is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.

Agent behavior: Before validating, check if okflint is installed (command -v okflint). If NOT installed, ask the user:

"okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:

uv tool install okflint (recomendado, isolado)

pip install okflint

Seguir sem ele (validação básica com o script bash embutido)"

If the user agrees to install:

# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint

# Option 2: pip (installs in current environment)
pip install okflint

# Verify installation
okflint --version

After installation (or if already available):

# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
  okflint validate --manifest okf-base.yaml ./bundle/
else
  # Core OKF validation only (no manifest needed)
  okflint validate ./bundle/
fi

okflint advantages over the built-in script:

Manifest-driven profiles (enforce custom required fields, status vocabularies, per-type constraints)
Wikilink resolution against full Obsidian vault
JSON output (--json) for CI pipeline parsing
Detects broken markdown links and ambiguous wikilinks
Exit codes: 0 = pass, 1 = conformance failure, 2 = bad manifest

Fallback: built-in bash script

When okflint is not installed, use scripts/validate.sh which checks the 3 core conformance rules plus v0.2 fields.

When asked to validate, check the 3 conformance rules. Report:

✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first

⚠  WARNING: 3 files missing 'description' field (recommended)
⚠  WARNING: 2 broken cross-links (permitted but worth noting)
ℹ  INFO: 5 files with trust fields (generated/verified)
ℹ  INFO: 2 Attested Computation concepts found

For a script-based check, see scripts/validate.sh.

Errors (conformance failures)

E1: File {path} has no YAML frontmatter
E2: File {path} has frontmatter but no type field (or empty)
E3: Reserved file {path} has unexpected structure
E4: Attested Computation missing required runtime field

Warnings (non-blocking, spec allows these)

W1: Missing recommended field title or description
W2: Broken cross-link {link} in {file}
W3: No generated field (v0.2 recommended)
W4: No index.md in directory {dir}
W5: log.md dates not in ISO 8601 format
W6: sources entry missing resource field
W7: stale_after date has passed — content is stale

Consumers MUST NOT reject a bundle because of: missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index files.

Enrich Concepts

When the user has existing OKF concepts that need enrichment:

Add schema section

For data assets, add # Schema with a columns table:

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique identifier |
| `customer_id` | STRING | FK to [customers](/tables/customers.md) |

Add examples section

For APIs, queries, or tools, add # Examples with fenced code blocks showing usage.

Add provenance (v0.2)

Add sources to frontmatter and footnotes to body for per-claim attribution:

sources:
  - id: official-docs
    resource: https://example.com/docs
    title: Official Documentation
    author: team:product-docs
    last_modified: 2026-07-15T00:00:00Z

Add trust signals (v0.2)

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-08-25T10:00:00Z }
verified: { by: human:domain-expert, at: 2026-08-25T14:00:00Z }
status: stable
stale_after: 2026-12-31T00:00:00Z

Add cross-links

Weave links into natural prose. Don't create a standalone "links" section — express relationships in context where they're meaningful.

Fill recommended fields

If title, description, tags are missing, add them. Derive values from body content when possible.

Enrichment workflow reference

The official enrichment agent follows this pattern — apply the same logic manually:

Start with metadata-only docs (just frontmatter + minimal body)
Add schema/structure from source system
Add sources from authoritative documentation
Weave cross-links based on discovered relationships (FKs, shared tags, join paths)
Generate index.md files for progressive disclosure
Add generated and optionally verified for trust tracking

Migrate v0.1 to v0.2

Breaking changes to address

timestamp → generated.at

# v0.1
timestamp: 2026-05-28T22:53:05Z

# v0.2
generated: { by: human:author, at: 2026-05-28T22:53:05Z }

# Citations → sources

# v0.1 body
# Citations
[1] https://example.com/docs

# v0.2 frontmatter
sources:
  - id: docs
    resource: https://example.com/docs
    title: Example Documentation

Migration script pattern

# For each .md file:
# 1. Extract timestamp, convert to generated
# 2. Parse # Citations, convert to sources
# 3. Add footnotes in body for citations

# Consumers MAY fall back to legacy fields when v0.2 fields absent

Backward compatibility

v0.2 consumers SHOULD:

Fall back to timestamp when generated is absent
Parse legacy # Citations when sources is absent

Convert Sources to OKF

For detailed conversion guides, see references/conversion.md.

Quick rules

Notion export: Properties → frontmatter. Remove UUID suffixes from filenames. Convert Notion links → relative markdown links.

Obsidian vault: Convert [[wikilinks]] → [title](./file.md). Ensure type field exists. Move inline #tags to frontmatter.

CSV/spreadsheet: Each row = one concept. Map columns to frontmatter fields. First column = filename.

Guardrails

NEVER invent data. If you don't know the correct type, ask. If you don't have schema info, leave it out. No fabricated URLs or column names.
Preserve unknown fields. OKF explicitly allows extension. Don't delete fields you don't recognize.
Don't impose taxonomy. Type values are free-form strings. Suggest descriptive values but never reject a bundle for having unexpected types.
Broken links are OK. The spec explicitly permits them — they represent not-yet-written knowledge.
Minimal by default. Generate only type (required) + recommended fields that are warranted. Don't pad with empty values.
Ask before assuming. If the domain is unclear, ask what types and structure make sense.
Respect trust hierarchy. Only mark as verified by human: if actually human-reviewed. Don't fabricate verification.
Computation integrity. Never edit the computation in an Attested Computation concept — only fill parameters.

Serve via Google Cloud Knowledge Catalog

Google Cloud's Knowledge Catalog natively ingests OKF bundles and serves them to agents. This is the enterprise path — optional but powerful.

kcmd CLI (Metadata as Code)

kcmd is a bidirectional sync tool between OKF-like local metadata and Knowledge Catalog. Think "git for metadata."

# Initialize from BigQuery dataset
kcmd init --bigquery-dataset <project>.<dataset>

# Pull current state from catalog
kcmd pull

# Push local changes
kcmd push --dry-run
kcmd push

Also ships as an MCP server for agent integration:

{
  "mcpServers": {
    "kc-mac": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/path/to/root"]
    }
  }
}

MCP tools: pull, push, list-entries, lookup-entry, modify-entry.

Reference Enrichment Agent

The official enrichment agent (Python, ADK, Gemini) auto-generates OKF bundles from BigQuery metadata. Two-pass architecture:

BQ pass — one OKF doc per table/view from metadata
Web pass — LLM crawls seed URLs and for each page decides to:
- (a) Enrich existing concepts with citations/schemas
- (b) Mint a new references/<slug> doc
- (c) Skip irrelevant content

Controls: --web-seed-file, --web-max-pages, --web-allowed-host, --no-web.

Visualizer

The reference agent includes a visualize subcommand that renders any OKF bundle as a self-contained interactive HTML file:

python -m reference_agent visualize --bundle ./bundles/<name>

Features:

Force-directed graph of concepts with colored nodes by type
Detail panel with frontmatter and rendered markdown
"Cited by" backlinks
Search and type filtering

When to mention this to users: If they're enriching BigQuery datasets, point them to the reference agent. If they want enterprise catalog integration, point to kcmd.

Output Format

When creating a bundle, present results as:

Directory tree showing the full structure
Each file's content in fenced code blocks
Conformance check confirming the bundle passes the 3 rules
Trust summary (v0.2) showing verified/unverified counts

saas-metrics/
├── index.md
├── log.md
├── metrics/
│   ├── index.md
│   ├── mrr.md
│   ├── churn.md
│   └── nps.md
└── computations/
    └── mrr-calculation.md

Then show each file, then confirm:

Bundle is OKF v0.2 conformant ✅
- 4 concept files
- 1 Attested Computation
- 3 human-verified, 1 unverified
- 0 stale concepts

发现问题？提交给管理员复核

暂无评论，成为第一个评论者吧！

okf-open-knowledge-format

复制安装命令

项目 README

🧠 AI Agent Skills — Open Source Collection for Claude Code, Cursor, Kiro & OpenCode

Available Skills

💡 Startup Idea · data-fetching-and-analysis

🔍 GEO Optimization (Generative Engine Optimization) · code-quality-and-review

📰 Substack Expert · library-and-api-reference

☁️ Pier Cloud API · library-and-api-reference

🎨 Ultimate Design System Master · code-scaffolding-and-templates

🗂️ Front-End Checklist (moved)

🚀 Coolify Operator · ci-cd-and-deployment

📄 Resume ATS Beater + LinkedIn Optimizer · code-scaffolding-and-templates

🤖 Agent Ready — Cloudflare Scanner · product-verification

✅ DESIGN.md Validator · product-verification

🔁 Ralph Loop for Kiro Specs · code-scaffolding-and-templates

🏗️ Loop Architect — Agent Loop Design Coach · code-scaffolding-and-templates

👑 Pstack Skills — 23 Playbooks for Claude Code, Cursor & OpenCode · code-quality-and-review

✍️ Humanizar — AI Text Humanizer for Brazilian Portuguese · code-quality-and-review

🌐 Human-AI — AI Text Humanizer for English · code-quality-and-review

🔐 auth.md — Agent Authentication Protocol · library-and-api-reference

📦 OKF — Open Knowledge Format · library-and-api-reference

🌐 Website Spec (moved)

🔒 LGPD Check

🔒 LGPD.md

📊 Skill Evaluation · code-quality-and-review

🧹 Slop Eval — Design Slop Evaluator · code-quality-and-review

🛡️ Security Specialist · runbooks

🚀 Astro Sites Manager · ci-cd-and-deployment

🔌 Agent Plugin Eval · product-verification

💰 Revenue-Centric Design · runbooks

Installation

Via Skills.sh

Via SkillKit

Via Agent Skills CLI

Manual Installation

Repository Structure

Author

References

License

高风险

Codex — Git Clone 安装

Codex — 手动复制安装

Claude Code — Git Clone 安装

Claude Code — 手动复制安装

Cursor — Git Clone 安装

Cursor — 手动复制安装

GitHub Copilot — Git Clone 安装

GitHub Copilot — 手动复制安装

Windsurf — Git Clone 安装

Windsurf — 手动复制安装

Open Knowledge Format (OKF)

Design Principles

Key Terminology

Quick Reference — Frontmatter Fields

Core Fields (all concepts)

Trust & Lifecycle Fields (v0.2)

Provenance Fields (v0.2)

Attested Computation Fields (v0.2)

Reserved Filenames

Conventional Body Headings

Actor Convention

Trust Tiers

Create a Bundle

1. Determine scope and structure

2. Create concept documents

3. Cross-link concepts

4. Add provenance with footnotes (v0.2)

5. Generate index.md

6. Generate log.md (optional)

7. Declare version (optional)

8. Distribution

9. Verify conformance

Create an Attested Computation (v0.2)

When to use

Structure

Key rules

Linking to computations

Validate a Bundle

Preferred: okflint (when available)

💡 Startup Idea · `data-fetching-and-analysis`

🔍 GEO Optimization (Generative Engine Optimization) · `code-quality-and-review`

📰 Substack Expert · `library-and-api-reference`

☁️ Pier Cloud API · `library-and-api-reference`

🎨 Ultimate Design System Master · `code-scaffolding-and-templates`

🚀 Coolify Operator · `ci-cd-and-deployment`

📄 Resume ATS Beater + LinkedIn Optimizer · `code-scaffolding-and-templates`

🤖 Agent Ready — Cloudflare Scanner · `product-verification`

✅ DESIGN.md Validator · `product-verification`

🔁 Ralph Loop for Kiro Specs · `code-scaffolding-and-templates`

🏗️ Loop Architect — Agent Loop Design Coach · `code-scaffolding-and-templates`

👑 Pstack Skills — 23 Playbooks for Claude Code, Cursor & OpenCode · `code-quality-and-review`

✍️ Humanizar — AI Text Humanizer for Brazilian Portuguese · `code-quality-and-review`

🌐 Human-AI — AI Text Humanizer for English · `code-quality-and-review`

🔐 auth.md — Agent Authentication Protocol · `library-and-api-reference`

📦 OKF — Open Knowledge Format · `library-and-api-reference`

📊 Skill Evaluation · `code-quality-and-review`

🧹 Slop Eval — Design Slop Evaluator · `code-quality-and-review`

🛡️ Security Specialist · `runbooks`

🚀 Astro Sites Manager · `ci-cd-and-deployment`

🔌 Agent Plugin Eval · `product-verification`

💰 Revenue-Centric Design · `runbooks`