复制安装命令
用 Codex 或 Claude 安装复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它先审查 Skill 页面再帮你安装。
复制前请先查看来源、License 和安全提示。
🇧🇷 Versao em Portugues do Brasil
用 Codex 或 Claude 安装复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它先审查 Skill 页面再帮你安装。
复制前请先查看来源、License 和安全提示。
来源文件:README.md
🇧🇷 Versao em Portugues do Brasil
A collection of Agent 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.
Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. Each skill is a folder with a SKILL.md file containing metadata and instructions that agents load on demand via progressive disclosure. Learn more at agentskills.io.
code-quality-and-reviewOptimizes 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):
references/guiding-principles.mdlibrary-and-api-referenceSubstack 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):
references/formatting-best-practices.mdreferences/seo-output-example.mdlibrary-and-api-referenceComplete 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):
references/REFERENCE.mdcode-scaffolding-and-templatesGenerates 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):
references/briefing-questionnaire.mdImprovements in v2.2 (Mar 8, 2026):
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
ci-cd-and-deploymentMaster operator for Coolify — the self-hosted open-source deployment platform (alternative to Heroku/Vercel/Netlify). Manages applications, servers, databases and services via REST API and official CLI.
When to use: connect to Coolify instances, deploy/restart/stop applications, manage environment variables, list servers and databases, monitor deployment logs, manage multiple environments (dev/staging/prod), troubleshoot connection and auth issues.
Improvements in v1.1 (Mar 8, 2026):
code-scaffolding-and-templatesRewrites 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):
modo_linkedin (full profile audit with scoring) and modo_unificado (CV + LinkedIn with consistency check)humanizar skill (scoped to About/Summary sections)auditoria-linkedin.md, ssi.md, presets-formatos.mdproduct-verificationAudits 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.
product-verificationValidates 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.
code-scaffolding-and-templatesAutomated 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.
code-scaffolding-and-templatesDesign 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.
code-quality-and-reviewRewrites Brazilian Portuguese text to sound human, natural, and undetectable by AI detection tools. Removes AI slop patterns, restores semantic entropy, and injects voice and personality. 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:
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):
New in v1.3 (Jul 2026):
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)code-quality-and-reviewRewrites English text to sound human, natural, and undetectable by AI detection tools. Combines pattern detection (43 patterns across 3 tiers), statistical measurement (burstiness, TTR, entropy), and voice injection into a single iterative skill. Built on research from the RAID Benchmark (ACL 2024), NeurIPS 2023, and real-world testing that proved vocabulary bans alone FAIL — structural paraphrasing is what actually beats detectors.
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 hurts while structural paraphrasing drops detector accuracy from 70.3% to 4.6%.
Why it's different from the existing humanizer skills:
scripts/measure.py — deterministic TTR/burstiness/entropy calculation (zero dependencies)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.
library-and-api-referenceGenerates, 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
library-and-api-referenceCreate, 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
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
Migrated → This skill moved to github.com/lgpd-app/skills
Audits websites for compliance with Brazil's LGPD (Lei 13.709/2018).
code-quality-and-reviewEvaluate 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).
code-quality-and-reviewObjectively 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).
Companions: method inspired by skill-evaluation; for text (not design), human-ai and humanizar do the de-slopping.
runbooksFull-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:
validate-findings.cjs) for CI integrationArchitecture:
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):
steering/hunting.md with 9 attack classes and 12-angle hunting methodologyreferences/report-schema.json for structured findings with trace, conditions, execution, confidencescripts/validate-findings.cjs zero-dependency JSON schema validatorci-cd-and-deploymentComprehensive 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:
runbooksPlaybook 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.
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
You can install these skills using any compatible installer or manually. Below are the most popular options.
npx skills add https://github.com/fabricioctelles/skills
Or install a specific skill:
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 pier-cloud
npx skills add https://github.com/fabricioctelles/skills -s ultimate-design-system-master
npx skills add https://github.com/fabricioctelles/skills -s resume-ats-beater
npx skills add https://github.com/fabricioctelles/skills -s coolify-operator
npx skills add https://github.com/fabricioctelles/skills -s agent-ready-cloudflare
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 humanizar
npx skills add https://github.com/fabricioctelles/skills -s auth-md
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 slop-eval
npx skills add https://github.com/fabricioctelles/skills -s revenue-centric-design
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
git clone https://github.com/fabricioctelles/skills.git
# 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/
# 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/
# 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/
The Agent Skills format is universal and works with any compatible agent. See the official specification for details.
skills/
├── geo-optimization/
│ ├── SKILL.md
│ └── references/ # guiding principles and case studies
├── substack-expert/
│ ├── SKILL.md
│ └── references/ # formatting best practices, SEO output example
├── pier-cloud/
│ ├── SKILL.md
│ ├── scripts/ # Python scripts for API consumption
│ └── references/ # API reference, troubleshooting guide
├── resume-ats-beater/
│ ├── SKILL.md
│ └── references/ # diagnostic templates, output structure
├── coolify-operator/
│ ├── SKILL.md
│ └── evals/ # 8 test scenarios
└── ultimate-design-system-master/
├── SKILL.md
└── references/ # briefing questionnaire, 10 specialized prompt files
├── 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.)
├── 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
├── humanizar/
│ ├── SKILL.md
│ └── references/ # 55+ AI patterns specific to Brazilian Portuguese (6 files)
├── auth-md/
│ ├── SKILL.md
│ └── references/ # protocol template, validation rules, metadata schema, example, implementation guide
│ ├── SKILL.md
│ └── references/ # 6 compliance check modules (privacy policy, cookies, data minimization, transfers, rights, scripts)
Created by ft.ia.br
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.
name: auth-md
description: >
Generate, validate, and explain `auth.md` files — the open protocol that lets AI agents
register for services on behalf of users. Use this skill whenever the user wants to make
their app agent-ready by publishing an `auth.md`, generate Protected Resource Metadata
(RFC 9728), validate an existing `auth.md` against the protocol specification, implement
agent registration endpoints, understand how the auth.md protocol works, or configure
authentication flows for agents. Trigger on mentions of "auth.md", "agent registration",
"agent auth", "make my app agent-ready", "ID-JAG", "identity_assertion flow",
"service_auth flow", "protected resource metadata", "claim ceremony", "agentic registration",
"CIMD", "Client ID Metadata Document", "oauth-id-jag", "agent revocation",
"agent credential", "agent discovery", "token exchange", "interaction_required",
"/.well-known/oauth-protected-resource", "/.well-known/oauth-authorization-server",
"/agent/identity", "/oauth2/token", or any variation of AI agent authentication/registration in APIs.
metadata:
author: https://ft.ia.br
version: "2.0"
date: 2026-06-27
repository: https://github.com/fabricioctelles/skills
license: Apache 2.0
category: library-and-api-referenceGenerate, validate, and explain the auth.md protocol — the open standard that lets AI agents register for services on behalf of users, without signup forms.
auth.md is a Markdown file published at a service's root (typically https://service.com/auth.md) that instructs agents on how to register. It works simultaneously as human-readable documentation and as a discoverable runtime artifact for agents.
The protocol extends RFC 9728 (OAuth 2.0 Protected Resource Metadata) with an agent_auth block in the Authorization Server metadata. Registration returns an identity_assertion (service-signed JWT) that the agent exchanges at /oauth2/token for an access_token. Three registration methods are supported:
| Flow | Mechanism | When to use |
|---|---|---|
| identity_assertion | Provider signs an ID-JAG (with auth_time) asserting user identity. Service verifies JWKS, returns identity_assertion. Agent exchanges at /oauth2/token. | Service does JIT provisioning from OIDC/SAML; wants zero-friction registration. |
| service_auth | Email hint + browser-based ceremony. Agent receives user_code + verification_uri; user signs in and types code. Agent polls /oauth2/token. | Agents on platforms that can't mint ID-JAGs; self-serve without trust list. |
| anonymous | No identity upfront. Immediate identity_assertion with pre-claim scopes. Optional deferred claim for scope upgrade. | Agent needs basic access immediately; human ownership binding deferred. |
| Endpoint | Purpose |
|---|---|
/.well-known/oauth-protected-resource | Discovery — resource metadata (RFC 9728) |
/.well-known/oauth-authorization-server | Discovery — AS metadata with agent_auth block |
POST /agent/identity | Registration — dispatches on type field |
POST /agent/identity/claim | Claim initiation (anonymous deferred, or re-initiate expired user_code) |
POST /oauth2/token | Token exchange (JWT-bearer grant) + claim polling (claim grant) |
POST /oauth2/revoke | Credential-layer revocation (RFC 7009) |
events_endpoint | Registration-layer revocation (receives SETs, RFC 8935) |
Registration never returns an access_token directly. The flow is:
identity_assertion (service-signed JWT, reusable until expiry)POST /oauth2/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer → access_tokenidentity_assertion when access_token expiresThe claim ceremony uses RFC 8628-style device authorization:
user_code + verification_uri in a claim blockverification_uri, signs in to the service, types the 6-digit codePOST /oauth2/token with grant_type=urn:workos:agent-auth:grant-type:claim + claim_tokenaccess_token + fresh identity_assertion| Parameter | Default | Description |
|---|---|---|
mode | generate | generate = create auth.md + metadata; validate = check existing auth.md; explain = explain the protocol |
validation_level | basic | basic = structure + fields + consistency (offline); full = basic + live endpoint fetch |
flows | all | Which flows to include: identity_assertion, service_auth, anonymous, all |
role | app | Perspective: app = service accepting registrations; provider = platform minting ID-JAGs |
Look for:
idJagMaxAuthAgeSeconds value (default: 3600)Produce three artifacts:
a) auth.md — Markdown file following the protocol template (see references/protocol-template.md). Must contain:
b) oauth-protected-resource.json — JSON for /.well-known/oauth-protected-resource with resource_name and resource_logo_uri
c) oauth-authorization-server.json — JSON for /.well-known/oauth-authorization-server with:
issuer, token_endpoint, revocation_endpoint, grant_types_supportedagent_auth block with identity_endpoint, claim_endpoint, events_endpoint"Next Steps" section with:
auth.md at the domain rootWWW-Authenticate header to 401 responses/oauth2/tokenWhen the user is an agent provider (not an app), generate:
auth_timeresource_name + resource_logo_uri)From a local file path or URL.
Basic (offline):
identity_endpoint, token_endpoint, grant_types_supportedidentity_types_supported in metadata JSONFull (live):
/.well-known/oauth-protected-resource from the declared base URLagent_auth block exists in AS metadata/.well-known/oauth-authorization-server and verify consistencyidentity_endpoint, token_endpoint, revocation_endpoint respond (accept 400/401/422, reject 404/405)WWW-Authenticate containing resource_metadataChecklist with ✅/❌ per rule, grouped by category:
Include severity: 🔴 Error (agents will fail), 🟡 Warning (degraded experience), 🟢 Info (suggestion).
See references/validation-rules.md for the complete ruleset.
When the user wants to understand the protocol without generating or validating:
The identity_assertion flow needs to decide which service user a registration represents. Recommended resolution order:
(iss, sub) has a delegation on file, route to same user(iss, sub) delegation → interaction_required (401) with claim block for user to confirm linkingReject ID-JAGs with neither a verified email nor a verified phone — there's no basis for matching.
The /agent/identity endpoint is unauthenticated for anonymous registration. Implement two tiers:
Also rate-limit /oauth2/token polling — enforce interval from the claim block, reject with slow_down if too fast.
| Event | When | Data |
|---|---|---|
registration.created | Successful POST /agent/identity | registration_id, registration_type, iss, sub |
registration.interaction_required | 401 interaction_required | registration_id, iss, sub, matched_user_id |
registration.login_required | 401 login_required | iss, sub, auth_time, max_age |
claim.initiated | /agent/identity/claim called | registration_id, email |
claim.completed | User submitted correct user_code | registration_id, claimed_by_user_id |
claim.expired | user_code window or registration expired | registration_id |
token.exchanged | /oauth2/token jwt-bearer success | registration_id, access_token_id |
token.revoked | /oauth2/revoke called | access_token_id |
registration.revoked | SET processed at events_endpoint | registration_id, iss, sub |
auth_time is required in ID-JAGs. Service validates against idJagMaxAuthAgeSeconds. If too old, returns login_required (401) — agent must get user to re-authenticate at provider.claim_token is a bearer secret. Store only SHA-256 hash server-side.resource_name and resource_logo_uri from PRM to the user before asserting identity. This is the user's only consent gate./oauth2/revoke, kills one access_token) vs registration layer (provider-driven SETs at events_endpoint, kills identity_assertion + all derived tokens).jti values with TTL of at least exp - iat + clock skew (typically 6 min).client_id is a URL, fetch as Client ID Metadata Document and verify jwks_uri.| Code | Where | Meaning |
|---|---|---|
anonymous_not_enabled | /agent/identity | Service doesn't accept anonymous |
service_auth_not_enabled | /agent/identity | service_auth disabled |
issuer_not_enabled | /agent/identity | Provider not on trust list |
invalid_request | /agent/identity | Body/claim/signature/jti/aud problems |
interaction_required (401) | /agent/identity | ID-JAG matched account, no delegation — claim needed |
login_required (401) | /agent/identity | auth_time too old — re-authenticate at provider |
invalid_claim_token | /agent/identity/claim | Token wrong or expired |
claimed_or_in_flight | /agent/identity/claim | Already claimed or wrong endpoint |
claim_expired | /agent/identity/claim | Registration expired |
invalid_grant | /oauth2/token | Assertion expired/revoked |
invalid_client | /oauth2/token | client_id not recognized |
unsupported_grant_type | /oauth2/token | Not jwt-bearer or claim grant |
authorization_pending | /oauth2/token (claim) | User hasn't completed ceremony |
expired_token | /oauth2/token (claim) | user_code window closed |
slow_down | /oauth2/token (claim) | Polling too fast |
rate_limited (429) | any | Back off and retry |
The isitagentready.com scanner validates auth.md as the authMd check. Pass criteria:
/auth.md served from site root with HTTP 200/.well-known/oauth-protected-resource/.well-known/oauth-authorization-serverTo pass the check minimally:
# auth.md
This service accepts AI agent registrations.
## Authentication
Agents can register via POST /agent/identity with a valid ID-JAG.
See below for supported methods.
To pass with full marks (all metadata):
/auth.md with proper heading/.well-known/oauth-protected-resource with resource, resource_name, resource_logo_uri, authorization_servers, scopes_supported, bearer_methods_supported: ["header"]/.well-known/oauth-authorization-server with issuer, token_endpoint, revocation_endpoint, grant_types_supported, and agent_auth block containing skill, identity_endpoint, claim_endpoint, events_endpoint, and registration methodsScan command:
curl -s -X POST 'https://isitagentready.com/api/scan' \
-H 'Content-Type: application/json' \
-d '{"url":"https://YOUR-DOMAIN/","enabledChecks":["authMd"]}' | jq '.checks.discovery.authMd'
Before delivering output, verify:
auth.md contains all required steps (1-6) + Errors + Revocationissuer, token_endpoint, revocation_endpoint, grant_types_supportedagent_auth block includes identity_endpoint, claim_endpoint, events_endpointidentity_types_supported matches the flows the user chosescopes_supported reflects actual API scopes found in codebase/oauth2/token with jwt-bearer grant{{...}}, <your-...>, [YOUR_...])auth_time documentedreferences/protocol-template.md — Complete auth.md template with all sections and placeholdersreferences/validation-rules.md — Full validation ruleset with error messages and severitiesreferences/metadata-schema.md — JSON schema for PRM, AS metadata, ID-JAG, and identity_assertionreferences/example-auth-md.md — Working example of a complete auth.md file (Acme Notes)references/implementation-guide.md — Server-side implementation guide with token exchange, claim ceremony, revocation, and securityThis skill ships with a snapshot of the auth.md protocol specification (v2, June 2026). When possible, fetch the latest version from:
https://auth-md.comhttps://raw.githubusercontent.com/workos/auth.md/refs/heads/main/AUTH.mdhttps://workos.com/auth-md/docshttps://workos.com/auth-md/docs/appshttps://workos.com/auth-md/docs/agent-providershttps://workos.com/auth-md/docs/auth-mdIf fetch fails, use the bundled references/ as the source of truth.
评论 (0)
暂无评论,成为第一个评论者吧!