{"id":48555750,"url":"https://github.com/pleaseai/ask","last_synced_at":"2026-04-12T20:05:05.617Z","repository":{"id":349786227,"uuid":"1199415068","full_name":"pleaseai/ask","owner":"pleaseai","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-07T14:33:58.000Z","size":1457,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T16:05:51.918Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pleaseai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T10:25:15.000Z","updated_at":"2026-04-07T14:03:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pleaseai/ask","commit_stats":null,"previous_names":["pleaseai/ask"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pleaseai/ask","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pleaseai","download_url":"https://codeload.github.com/pleaseai/ask/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fask/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31551891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T10:21:54.569Z","status":"ssl_error","status_checked_at":"2026-04-08T10:21:38.171Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-08T11:00:43.456Z","updated_at":"2026-04-12T20:05:05.595Z","avatar_url":"https://github.com/pleaseai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ASK (Agent Skills Kit)\n\nDownload version-specific library documentation for AI coding agents.\n\nInspired by [Next.js evals](https://nextjs.org/evals) showing that providing `AGENTS.md` with bundled docs dramatically improves AI agent performance (Claude Opus 4.6: 71% → 100%), ASK generalizes this pattern to any library.\n\n## How It Works\n\nASK uses a **lazy-first** architecture. You declare the libraries you\ncare about in a root-level `ask.json`, and `ask install` resolves\nversions from your lockfile and generates `AGENTS.md` + `SKILL.md`\nwith lazy documentation references. AI agents then access docs\non-demand via `ask src` / `ask docs` commands.\n\n```bash\nask add npm:next                              # Add to ask.json\nask add github:vercel/next.js@v14.2.3         # GitHub with inline ref\nask install                                   # Resolve versions + generate AGENTS.md/SKILL.md\n```\n\nAfter `ask add`, your `ask.json` looks like:\n\n```json\n{\n  \"libraries\": [\n    \"npm:next\",\n    \"github:vercel/next.js@v14.2.3\"\n  ]\n}\n```\n\nEach successful install:\n\n1. Resolves the version (lockfile for `npm:`, inline `@ref` for `github:`)\n2. Generates a Claude Code skill in `.claude/skills/\u003clibrary\u003e-docs/SKILL.md`\n   with `ask src` / `ask docs` references\n3. Generates/updates `AGENTS.md` with version warnings and lazy command references\n\nNo documentation is downloaded during install — agents access docs\non-demand via `ask src` / `ask docs`, which fetch and cache on first use.\n\n`ask install` is `postinstall`-friendly: failures on individual entries\nemit a warning and the command still exits 0.\n\n## Installation\n\n```bash\nbun install\nbun run build\n```\n\n## Monorepo Structure\n\n```\npackages/cli/       @pleaseai/ask CLI (npm publishable)\napps/registry/      ASK Registry browser (Nuxt + Nuxt Content v3, Cloudflare Pages)\n```\n\n## Usage\n\n### Add a library\n\n```bash\n# PM-driven npm entry — version comes from your lockfile at install time\nask add npm:next\nask add npm:@mastra/client-js\n\n# GitHub entry with inline ref\nask add github:vercel/next.js@v14.2.3\nask add vercel/next.js@v14.2.3              # github: prefix is implied for owner/repo\n```\n\n`ask add` appends a spec string to `ask.json` and immediately runs\ninstall for that single entry.\n\n### Install all declared libraries\n\n```bash\nask install            # Resolve versions + generate AGENTS.md/SKILL.md\n```\n\n`ask install` reads `ask.json`, resolves each entry's version\n(lockfile for `npm:`, inline `@ref` for `github:`), and generates `AGENTS.md` and `.claude/skills/\u003cname\u003e-docs/SKILL.md`\nwith lazy references (`ask src` / `ask docs`). No documentation is\ndownloaded — agents fetch docs on-demand.\n\n```jsonc\n// package.json\n{\n  \"scripts\": {\n    \"postinstall\": \"ask install\"\n  }\n}\n```\n\n### List declared libraries\n\n```bash\nask list           # Tabular view of ask.json + resolved versions\nask list --json    # Same data as ListModelSchema-conformant JSON\n```\n\n### Remove a library\n\n```bash\nask remove next\nask remove @mastra/client-js\nask remove github:vercel/next.js\n```\n\n`ask remove` deletes the matching spec from `ask.json`, removes the\nskill file, and regenerates the `AGENTS.md` block.\n\n### Lazy commands (primary docs access)\n\n`ask src` and `ask docs` are the **primary way agents access\ndocumentation**. They print absolute paths to cached source trees,\nfetching on cache miss:\n\n```bash\nask src \u003cspec\u003e     # Print the absolute path to a cached library source tree\nask docs \u003cspec\u003e    # Print all candidate documentation paths from node_modules + the cached source\n```\n\nBoth commands fetch on cache miss (first run) and short-circuit on cache\nhit. They share the same `~/.ask/github/github.com/\u003cowner\u003e/\u003crepo\u003e/\u003ctag\u003e/`\nstore.\n\n```bash\n# Print the absolute path to React's source tree (fetches on first run)\nask src react\n\n# Grep across the full React source via shell substitution\nrg \"useState\" $(ask src react)\n\n# Print all docs candidates for vue — one path per line, agent picks\nask docs vue\n\n# Search across every monorepo docs/ directory at once\nrg \"defineComponent\" $(ask docs vue)\n\n# CI guard: exit 1 if the cache is empty\nask src react --no-fetch\n```\n\n**Spec syntax** — same `npm:`/`github:`/ecosystem-prefixed format as\n`ask add`, plus an optional trailing `@version`:\n\n```bash\nask src react                              # latest from npm registry\nask src react@18.2.0                       # explicit version\nask src @vercel/ai@5.0.0                   # scoped npm name + version\nask src github:facebook/react              # github default branch\nask src github:facebook/react@v18.2.0      # github tag\nask src pypi:requests                      # cross-ecosystem\n```\n\n**Version resolution priority** for npm specs without an explicit\n`@version`: project lockfile → resolver \"latest\". Explicit `@version`\nalways wins.\n\n**Registry-free** — neither command consults the curated ASK Registry; both\ngo straight to upstream package metadata.\n\n`ask docs` walks `node_modules/\u003cpkg\u003e/` only for npm-ecosystem specs (not\nfor `github:`/`pypi:`/etc.), and surfaces every subdirectory whose name\nmatches `/doc/i` up to depth 4, skipping `node_modules`, `.git`, `.next`,\n`.nuxt`, `dist`, `build`, `coverage`, and dotdirs. The source root is\nalways emitted as the first line so the agent can fall back to it when no\n`docs/` directory exists.\n\n## Registry\n\nThe ASK Registry (`apps/registry/`) is a community-maintained catalog of library documentation configs. Each entry is a Markdown file with YAML frontmatter:\n\n```\napps/registry/content/registry/\n├── vercel/           # github owner\n│   └── next.js.md\n├── colinhacks/       # github owner\n│   └── zod.md\n├── tailwindlabs/     # github owner\n│   └── tailwindcss.md\n└── ...               # one directory per github owner\n```\n\n### Registry entry format\n\n```markdown\n---\nname: Next.js\ndescription: The React framework by Vercel\nrepo: vercel/next.js\ndocsPath: docs\nhomepage: https://nextjs.org\nlicense: MIT\naliases:\n  - ecosystem: npm\n    name: next\nstrategies:\n  - source: npm\n    package: next\n    docsPath: dist/docs\n  - source: github\n    repo: vercel/next.js\n    docsPath: docs\ntags: [react, framework, ssr]\n---\n\nDescription and version notes here...\n```\n\n### Contributing\n\nAdd a new `.md` file under `apps/registry/content/registry/\u003cgithub-owner\u003e/` and submit a PR.\n\n## Ecosystem Resolvers\n\nWhen a library isn't in the registry, ASK can **automatically resolve** its GitHub repository from ecosystem package metadata. This works for any ecosystem-prefixed spec:\n\n```bash\nask add npm:lodash       # Looks up registry.npmjs.org → lodash/lodash\nask add pypi:fastapi     # Looks up pypi.org → fastapi/fastapi\nask add pub:riverpod     # Looks up pub.dev → rrousselGit/riverpod\n```\n\n**Supported ecosystems:**\n\n| Ecosystem | API | Metadata field |\n|---|---|---|\n| `npm` | `registry.npmjs.org/\u003cname\u003e` | `repository.url` |\n| `pypi` | `pypi.org/pypi/\u003cname\u003e/json` | `info.project_urls.Source` |\n| `pub` | `pub.dev/api/packages/\u003cname\u003e` | `latest.pubspec.repository` |\n\nThe resolver extracts the GitHub `owner/repo` from the package metadata and delegates to the GitHub source for download. The registry is always checked first — resolvers only activate on a registry miss.\n\n## Source Adapters\n\n### npm\n\nExtracts documentation from npm package tarballs.\n\n### GitHub\n\nDownloads documentation from a GitHub repository at a specific tag or branch.\n\n### Web\n\nCrawls documentation websites and converts HTML to Markdown.\n\n## Global Store\n\nASK maintains a global docs store at `~/.ask/` so identical `\u003cpkg\u003e@\u003cversion\u003e` entries are fetched once per machine and reused across projects.\n\n```\n~/.ask/                                     # ASK_HOME\n├── STORE_VERSION                           # always \"2\"\n├── npm/\n│   └── next@16.2.3/                        # immutable doc entry\n├── github/\n│   └── github.com/                         # host (reserved — gitlab/bitbucket later)\n│       └── vercel/next.js/v16.2.3/         # per-tag shallow clone, .git/ stripped\n├── web/\n│   └── \u003csha256\u003e/                           # crawled snapshots\n└── llms-txt/\n    └── \u003csha256\u003e@\u003cversion\u003e/\n```\n\n### Legacy layout migration\n\nIf you upgraded from an older ASK, you may have a legacy\n`~/.ask/github/{db,checkouts}/` tree left behind. Running `ask install`\nprints a one-line warning on first touch pointing at the cleanup\ncommand:\n\n```bash\nask cache clean --legacy\n```\n\nThe command is idempotent and safe to run on a clean tree.\n\n### `ASK_HOME`\n\nOverride the store location: `ASK_HOME=/path/to/store ask install`\n\n### Cache management\n\n```bash\nask cache ls                   # list store entries with sizes\nask cache ls --kind npm        # filter by kind\nask cache gc --dry-run         # preview what would be removed\nask cache gc                   # remove unreferenced entries\n```\n\n## Eval Results\n\nWe run our own eval suite ([`evals/nuxt-ui/`](evals/nuxt-ui/)) comparing documentation strategies on 6 Nuxt UI v4 tasks — including 3 breaking-change evals with negative assertions that catch deprecated v2/v3 API usage.\n\n### Doc source comparison (claude-sonnet-4-6, 2026-04-07)\n\n| Doc source | Pass rate | Est. cost | Retries needed |\n|---|---|---|---|\n| **ASK github-docs (AGENTS.md)** | **100%** (6/6) | **$1.67** | 0 |\n| No docs (baseline) | 86% (6/7) | $1.82 | 1 |\n| llms-full.txt (~200KB) | 46% (6/13) | $2.93 | 7 |\n| llms.txt (~5KB) | 40% (6/15) | $4.83 | 9 |\n\n**Key findings:**\n\n- **ASK-style docs outperform all alternatives** — 100% pass rate at the lowest cost. Structured docs with version warnings let the agent find correct v4 APIs without excessive exploration.\n- **llms.txt / llms-full.txt hurt more than they help** — Both scored below baseline. The agent spends tokens searching through unstructured docs but still uses deprecated patterns.\n- **Cost scales inversely with quality** — The worst performer (llms.txt) costs 2.9x more than the best (ASK github-docs), driven by retry loops and exploratory tool calls.\n\n### Delivery format comparison: AGENTS.md vs Claude Code skill (2026-04-10)\n\nSame docs payload, same model, same sandbox — only the delivery format changes:\n\n| Delivery format | First-try pass rate | Notes |\n|---|---|---|\n| **AGENTS.md pointer** | **100%** (6/6) | Baseline ASK behavior |\n| `.claude/skills/\u003cpkg\u003e-docs/SKILL.md` | 50% (3/6) | Failed first-try on 3 breaking-change evals (001, 003, 005); only recovered on retry |\n\nThis reproduces [Vercel's public finding](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)\n(\"AGENTS.md outperforms skills in our agent evals\") inside ASK's own suite.\n\nSee [`evals/nuxt-ui/README.md`](evals/nuxt-ui/README.md) for full methodology and detailed results.\n\n## Background\n\nThe [Next.js evals](https://nextjs.org/evals) benchmark ([source code](https://github.com/vercel/next-evals-oss)) showed that AI agents perform significantly better when given access to version-specific documentation via `AGENTS.md`:\n\n| Agent | Without docs | With AGENTS.md |\n|-------|-------------|----------------|\n| Claude Opus 4.6 | 71% | **100%** |\n| Gemini 3.1 Pro | 76% | **100%** |\n| GPT 5.3 Codex | 86% | **100%** |\n\nASK makes it easy to apply this pattern to any library in any project.\n\n## Related Projects\n\n- [next-evals-oss](https://github.com/vercel/next-evals-oss) — Vercel's open-source Next.js agent evals showing AGENTS.md impact\n- [skills-npm](https://github.com/antfu/skills-npm) — Convention for shipping agent skills inside npm packages (maintainer-side)\n- [TanStack Intent](https://github.com/TanStack/intent) — CLI for generating, validating, and shipping Agent Skills with npm packages\n- [Skilld](https://github.com/skilld-dev/skilld) — Generates agent skills from npm dependencies using docs, release notes, and GitHub discussions\n- [mdream](https://github.com/harlan-zw/mdream) — High-performance HTML to Markdown converter optimized for LLM applications\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpleaseai%2Fask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpleaseai%2Fask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpleaseai%2Fask/lists"}