{"_id":"@dualnova/agent-skills","name":"@dualnova/agent-skills","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@dualnova/agent-skills","version":"0.1.0","description":"Validator and reference implementation for the agent-skills standard — machine-readable instructions that let AI assistants (ChatGPT, Claude, Perplexity, Gemini) execute capabilities on your site's behalf.","keywords":["agent-skills","well-known","ai-agents","geo","generative-engine-optimization","mcp","model-context-protocol","ai-search","agent-ready","skill-discovery","chatgpt-actions","claude-tools","perplexity","gemini","openapi"],"homepage":"https://github.com/DualNova/agent-skills#readme","bugs":{"url":"https://github.com/DualNova/agent-skills/issues"},"repository":{"type":"git","url":"git+https://github.com/DualNova/agent-skills.git"},"author":{"name":"DualNova LLC","email":"hello@dualnova.org","url":"https://dualnova.org"},"license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"agent-skills":"dist/cli.js"},"scripts":{"build":"tsc","test":"node --test --import tsx test/*.test.ts","lint":"tsc --noEmit","prepublishOnly":"npm run lint && npm run test && npm run build"},"devDependencies":{"@types/node":"^22.0.0","tsx":"^4.19.0","typescript":"^5.6.0"},"engines":{"node":">=20"},"_id":"@dualnova/agent-skills@0.1.0","gitHead":"2d83692237fde1fb3924dbf6d32991c61bc36f0d","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-EB/fKZ2AwSvC/MKbeC5/0x41aJAyV34Y8TGXfRdUz1/IgL3zt9NXCqX5hkOJIwYOuhluPBvdax3roWxeiPtqDw==","shasum":"d6a8ed33deb9f15935b52d1cc18f3b7bbb686ed8","tarball":"https://registry.npmjs.org/@dualnova/agent-skills/-/agent-skills-0.1.0.tgz","fileCount":23,"unpackedSize":68264,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dualnova%2fagent-skills@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEdeFUpuRDuwdGUoQst90MjQfv9lH4l4WDBHMRH8UlsQAiBjxiSYPKDNz/44FewlxiU/5lLLwppGf4XW3a/W+WGS4g=="}]},"_npmUser":{"name":"miguelesco","email":"miguelangelescorche@gmail.com"},"directories":{},"maintainers":[{"name":"miguelesco","email":"miguelangelescorche@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-skills_0.1.0_1779904038966_0.15070562725069192"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T17:47:18.769Z","0.1.0":"2026-05-27T17:47:19.139Z","modified":"2026-05-27T17:47:19.516Z"},"maintainers":[{"name":"miguelesco","email":"miguelangelescorche@gmail.com"}],"description":"Validator and reference implementation for the agent-skills standard — machine-readable instructions that let AI assistants (ChatGPT, Claude, Perplexity, Gemini) execute capabilities on your site's behalf.","homepage":"https://github.com/DualNova/agent-skills#readme","keywords":["agent-skills","well-known","ai-agents","geo","generative-engine-optimization","mcp","model-context-protocol","ai-search","agent-ready","skill-discovery","chatgpt-actions","claude-tools","perplexity","gemini","openapi"],"repository":{"type":"git","url":"git+https://github.com/DualNova/agent-skills.git"},"author":{"name":"DualNova LLC","email":"hello@dualnova.org","url":"https://dualnova.org"},"bugs":{"url":"https://github.com/DualNova/agent-skills/issues"},"license":"MIT","readme":"# @dualnova/agent-skills\n\n> Validator and reference implementation for the **agent-skills standard** — machine-readable instructions that let AI assistants (ChatGPT, Claude, Perplexity, Gemini) execute capabilities on your site's behalf.\n\n[![npm](https://img.shields.io/npm/v/@dualnova/agent-skills.svg)](https://www.npmjs.com/package/@dualnova/agent-skills)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Spec](https://img.shields.io/badge/spec-draft%20v0.1-orange.svg)](spec/SPEC.md)\n\n> 🇪🇸 [Léeme en español](#-léeme-en-español)\n\n---\n\n## The problem\n\nWhen an AI assistant wants to perform an action on a user's behalf — book a call, get a quote, submit a contact form, look up availability — it currently has three options:\n\n1. **Read prose.** Crawl the site and guess from the HTML what the user can do. Brittle, expensive, error-prone.\n2. **OpenAPI.** Discover the API spec and call it directly. Works for backend integrations but doesn't tell the assistant *when* to invoke a capability, *what info to collect first*, or *what to tell the user about expectations*.\n3. **MCP server.** Establish a session and expose tools. Excellent for tightly-coupled agents (Claude Desktop, IDEs) but heavyweight for a one-off public capability.\n\n**Agent Skills fills the gap.** A static `SKILL.md` file describes one capability in a single page of Markdown, optimized for an LLM to read and follow. The site says \"here is what you can do; here is when to use it; here is what to tell the user.\" The assistant follows the recipe.\n\n## The spec in 30 seconds\n\n```\n/.well-known/agent-skills/\n├── index.json              ← machine-readable registry\n├── book-call/SKILL.md      ← one skill\n├── get-quote/SKILL.md      ← another skill\n└── contact-form/SKILL.md\n```\n\nEach `SKILL.md` is YAML frontmatter + Markdown body:\n\n```markdown\n---\nname: book-discovery-call\ndescription: Book a free 30-minute discovery call with the team.\nversion: 1.0\nprovider: Acme Studio\nurl: https://acme-studio.example/contact\nlanguages: [en, es]\n---\n\n# Book a Discovery Call\n\n## When to invoke this skill\nWhen a user wants to talk to a real person before committing.\n\n## Step-by-step flow for the assistant\n1. Confirm intent.\n2. Collect name, email, project description, preferred language.\n3. Direct the user to https://acme-studio.example/contact.\n4. Tell them: 30 min, free, video call, confirmation in 1 min.\n\n## Fallback\nEmail hello@acme-studio.example.\n```\n\nRead the full spec: [`spec/SPEC.md`](spec/SPEC.md).\n\n## Why publish skills?\n\n| Goal | Without agent-skills | With agent-skills |\n|------|---------------------|-------------------|\n| **A user asks Claude \"book me a call with Acme\"** | Claude crawls the site, guesses how the form works, may invent fields or links. | Claude reads the SKILL.md, follows the recipe verbatim, collects the right info, sets correct expectations. |\n| **Cloudflare's `isitagentready.com` audit** | Flags missing skills as a deficiency in the *API, Auth, MCP & Skill Discovery* section. | Score goes up; site shows as \"agent-ready\". |\n| **Future agent marketplaces** (Anthropic, OpenAI roadmap) | No way to register a capability without code. | Static `.md` files can be ingested as-is. |\n\n## Install\n\n```sh\nnpm install -D @dualnova/agent-skills\n# or run without installing\nnpx @dualnova/agent-skills validate-site --url https://your-site.example\n```\n\n## CLI\n\n```sh\n# Validate a single SKILL.md\nagent-skills validate ./public/.well-known/agent-skills/book-call/SKILL.md\n\n# Validate the index.json\nagent-skills validate-index ./public/.well-known/agent-skills/index.json\n\n# Crawl a live site: fetches index.json + every linked SKILL.md and validates them all\nagent-skills validate-site --url https://dualnova.org\n```\n\nSample output:\n\n```\nFetching https://dualnova.org/.well-known/agent-skills/index.json\nIndex: ✓\n\nSkill https://dualnova.org/.well-known/agent-skills/booking-call/SKILL.md\n  ✓ No issues.\n\n✓ site total: 0 error(s), 0 warning(s)\n```\n\n## CI integration\n\n```yaml\n# .github/workflows/agent-skills.yml\nname: Validate agent skills\non: [push, pull_request]\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with: { node-version: '20' }\n      - run: |\n          for f in $(find public/.well-known/agent-skills -name SKILL.md); do\n            npx -y @dualnova/agent-skills validate \"$f\"\n          done\n          npx -y @dualnova/agent-skills validate-index public/.well-known/agent-skills/index.json\n```\n\n## Programmatic API\n\n```typescript\nimport { validateSkill, validateIndex } from '@dualnova/agent-skills';\nimport { readFileSync } from 'node:fs';\n\nconst result = validateSkill(readFileSync('./SKILL.md', 'utf8'));\nif (!result.valid) {\n  for (const issue of result.issues.filter(i => i.severity === 'error')) {\n    console.error(`✗ ${issue.message}`);\n  }\n  process.exit(1);\n}\n\nconsole.log(`Parsed skill: ${result.parsed.frontmatter.name}`);\n```\n\n## Examples\n\nThe [`spec/examples/`](spec/examples) directory contains three production-grade SKILL.md files you can adapt:\n\n- [`book-call/SKILL.md`](spec/examples/book-call/SKILL.md) — schedule a discovery call\n- [`get-quote/SKILL.md`](spec/examples/get-quote/SKILL.md) — request a fixed-price quote (with OpenAPI reference)\n- [`contact-form/SKILL.md`](spec/examples/contact-form/SKILL.md) — generic message form\n\n## Reference deployments\n\n| Site | Skills published |\n|------|-----------------|\n| [dualnova.org](https://dualnova.org/.well-known/agent-skills/index.json) | `book-discovery-call` |\n\nWant yours listed? Open a PR adding to the table above.\n\n## Relationship to other standards\n\n| Standard | Relationship |\n|----------|--------------|\n| `robots.txt` | Orthogonal. agent-skills assumes AI search bots are allowed. |\n| [`/llms.txt`](https://llmstxt.org) | Complementary. llms.txt can link to the agent-skills index. See [`@dualnova/llms-txt`](https://github.com/DualNova/llms-txt). |\n| [Schema.org `potentialAction`](https://schema.org/Action) | Complementary. The execution page can include `additionalProperty` pointing to the SKILL.md. |\n| [OpenAPI](https://www.openapis.org/) | Complementary. SKILL.md can reference an `openapi` URL in frontmatter. |\n| [MCP](https://modelcontextprotocol.io) | Complementary. SKILL.md can reference an `mcp_server` URL in frontmatter. |\n\n## Status\n\n**Draft v0.1 — May 2026.** This spec is intentionally tiny so the migration path is short. Breaking changes will bump the major version in `index.json`'s `version` field. Sites are encouraged to publish today.\n\nWe're collecting feedback in [Discussions](https://github.com/DualNova/agent-skills/discussions). If you publish skills on your site, let us know — we'll add you to the reference deployments table.\n\n## License\n\n- The **specification** ([`spec/SPEC.md`](spec/SPEC.md)) is [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).\n- The **library and CLI** are [MIT](LICENSE).\n\nBoth © 2026 [DualNova LLC](https://dualnova.org).\n\n---\n\n## 🇪🇸 Léeme en español\n\n### El problema\n\nCuando un asistente AI quiere ejecutar una acción a nombre del usuario — agendar una llamada, pedir cotización, enviar un formulario — tiene tres opciones hoy: leer el HTML del sitio y adivinar, llamar a tu API por OpenAPI, o conectarse a un MCP server. **Agent Skills cubre el hueco**: un archivo estático `SKILL.md` describe una capacidad en una página de Markdown optimizada para que un LLM la lea y la siga.\n\n### En 30 segundos\n\n```\n/.well-known/agent-skills/\n├── index.json              ← registro machine-readable\n└── nombre-skill/SKILL.md   ← una skill, en Markdown con YAML frontmatter\n```\n\nLee el spec completo en [`spec/SPEC.md`](spec/SPEC.md).\n\n### Instalación\n\n```sh\nnpx @dualnova/agent-skills validate-site --url https://tu-sitio.example\n```\n\n### Ventajas\n\n- Cuando un usuario pide a Claude \"agenda una llamada con Acme\", Claude lee el `SKILL.md`, sigue el flujo, recolecta la info correcta y setea expectativas correctas — en vez de adivinar del HTML.\n- Sube el score en auditorías de \"agent-readiness\" (Cloudflare `isitagentready.com`).\n- Listo para marketplaces de agentes que Anthropic y OpenAI están construyendo.\n\n### Licencia\n\n- Spec: CC BY 4.0\n- Librería/CLI: MIT\n\nAmbos © 2026 [DualNova LLC](https://dualnova.org) — equipo bilingüe basado en Caracas, Bogotá y Miami.\n\n---\n\n**Built by [DualNova](https://dualnova.org)** — blockchain and AI software development for LATAM and the US.\n","readmeFilename":"README.md","_rev":"1-080c8d12b0c2ea0ff9285cd31daef445"}