docs(skills): add ask skill with references for progressive disclosure

[amondnet]

Summary

• Adds skills/ask/SKILL.md — teaches agents the $(ask docs <spec>) / $(ask src <spec>) subshell idiom so they resolve accurate, version-matched doc paths at runtime rather than relying on training-data guesses.
• Adds three skills/ask/references/ files for progressive disclosure: cache.md (store layout, ASK_HOME, gc/quarantine), declarative-workflow.md (ask.json schema, strict ref validation, install pipeline, intent-format distinction), and skills-vendoring.md (ask skills install/remove, --agent flag, vendored dir layout).
• Modeled on vercel-labs/opensrc's skills/opensrc/SKILL.md; command surface verified against packages/cli/src/.

Test plan

• Docs-only change; no code modified.
• Manual review: confirm SKILL.md frontmatter is valid, one-shot command table matches live CLI, and references/ relative links resolve correctly from the skill body.

---

Summary by cubic

Adds a new ask skill that teaches agents to use $(ask docs <spec>), $(ask src <spec>), and $(ask skills <spec>) for version-accurate docs, source, and producer skills pinned to the project’s lockfile. Aligns the declarative workflow docs with the lazy-first ask install model and removes stale flags/examples.

• New Features
  • Added skills/ask/SKILL.md with the subshell pattern, spec grammar, and one-shot commands; clarifies output shapes (docs emits candidate dirs, src a single checkout root); drops strict-ref validation phrasing.
  • Added skills/ask/references/ for progressive disclosure: cache management (ASK_HOME, cache ls/gc/clean, v2 layout/quarantine), declarative workflow (strict spec-string ask.json, lazy-first ask install = version resolve + SKILL.md + AGENTS.md, correct ask list --json .entries[], removed --allow-mutable-ref, .ask/resolved.json not written), and skills vendoring (ask skills install/remove, --agent/--force/--no-fetch, vendored layout and lock behavior).

^{Written for commit 877367e. Summary will update on new commits.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	877367e
Status:	⚡️  Build in progress...

View logs

[cubic-dev-ai]

No issues found across 4 files

_{Auto-approved: Docs-only change adding agent skill instructions and reference files for the 'ask' tool. No source code modified; zero risk of breaking production logic.}

Architecture diagram

sequenceDiagram
    participant Agent as Agent / User
    participant CLI as ask CLI
    participant FS as Local Project FS
    participant Cache as Global Cache (~/.ask)
    participant Remote as External (NPM/GitHub)

    Note over Agent,Remote: Dynamic Discovery Flow (One-Shot)

    Agent->>CLI: NEW: $(ask docs <spec>) or $(ask src <spec>)
    CLI->>FS: Read lockfile (bun/npm/pnpm/yarn)
    FS-->>CLI: Resolved Version/Ref
    
    CLI->>Cache: Check for <spec>@version (v2 layout)
    alt Cache Miss
        CLI->>Remote: Fetch source/tarball
        Remote-->>CLI: Source data
        CLI->>Cache: NEW: Store in <ASK_HOME>/<kind>/<key>
    end
    
    CLI-->>Agent: NEW: Absolute path to stdout
    Agent->>Cache: Access files via standard tools (cat, rg, fd)

    Note over Agent,Remote: Declarative Workflow (ask install / add)

    Agent->>CLI: ask install
    CLI->>FS: Read ask.json
    
    loop Every library in ask.json
        alt NEW: Strict Ref Validation
            CLI->>CLI: Reject mutable refs (main/latest) unless --allow-mutable-ref
        end
        
        CLI->>CLI: Resolve & Fetch (same as One-Shot)
        
        CLI->>FS: NEW: Materialize .ask/docs/<name>
        CLI->>FS: NEW: Generate .claude/skills/<name>-docs/SKILL.md
        CLI->>FS: NEW: Update AGENTS.md auto-generated blocks
        
        opt NEW: Intent-Format Package
            CLI->>FS: Write to intent-skills block in AGENTS.md
        end
    end

    Note over Agent,Remote: Skill Vendoring (ask skills install)

    Agent->>CLI: NEW: ask skills install <spec>
    CLI->>Cache: Locate skills/ directory in source
    CLI->>FS: NEW: Vendor to .ask/skills/<specKey>/
    
    alt Agent Detection
        CLI->>FS: Check for .claude/, .cursor/, .opencode/, etc.
        FS-->>CLI: Detected paths
    else Explicit Agent
        Agent->>CLI: --agent <names>
    end
    
    CLI->>FS: NEW: Symlink vendored skills into agent directories
    CLI->>FS: Update .ask/skills-lock.json

Loading

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/ask/SKILL.md">

<violation number="1" location="skills/ask/SKILL.md:55">
P3: "nothing is persisted" is misleading: one-shot commands do persist fetched data in the global ASK cache. Clarify that only project declarative state is not persisted.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P3: "nothing is persisted" is misleading: one-shot commands do persist fetched data in the global ASK cache. Clarify that only project declarative state is not persisted.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/ask/SKILL.md, line 55:

<comment>"nothing is persisted" is misleading: one-shot commands do persist fetched data in the global ASK cache. Clarify that only project declarative state is not persisted.</comment>

<file context>
@@ -49,10 +49,10 @@ github:owner/repo@main          # pinned branch
+  (no `@ref`) defaults to `main`.
+- Any ref works with these one-shot reading commands — branches, tags,
+  or mutable refs like `main` / `master` are all accepted, since
+  nothing is persisted.
 
 ## One-Shot Reading Commands
</file context>