llms.txt + served AGENTS.md: guide into a skills-mode choice - #251
Merged
Conversation
llms.txt now leads with the on-demand fetch mechanics (so cross-links and any agent get usable guidance immediately, never blocked) and then offers a one-time choice — on-demand / pinned / autosync — with an ask-first, non-destructive option to persist it into the project's AGENTS.md. The served /AGENTS.md now matches the icp-cli-templates onboarding file, so curl-ing it equals scaffolding. README gains the quick-start paste prompt. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 23, 2026
Merged
… curl example - Fetch the skills index once per session (remember names/URLs) instead of per task. - Pinned update policy is 'manual' or 'ask-first' (no silent auto); ask-first never blocks and skips in non-interactive sessions. - Make explicit that the on-demand fetch path needs no terminal and no install, so web-only agents (e.g. Perplexity) that can fetch URLs are handled; the .well-known index is the always-available default. Add a correct 'curl -sL' example. - Served /AGENTS.md stays in sync with the icp-cli-templates onboarding file. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The served /AGENTS.md was unreferenced and duplicated the AGENTS.md content (the Get Started page embedded its own stale copy). Delete the endpoint and rework Get Started to organise by intent: use skills with your agent (paste prompt), start a new project with icp-cli (ships a self-configuring AGENTS.md), pin into an existing project (npx skills), and browse/read skills yourself. No AGENTS.md copy remains on the site; llms.txt is the sole agent entrypoint. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
'No install' applies to the default on-demand fetch; if you pin or enable auto-update, the agent runs that setup for you. Reword so the page doesn't imply the whole flow is install-free. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
marc0olo
marked this pull request as ready for review
July 27, 2026 10:55
'No install required' was only true for the default on-demand fetch; pinning or auto-updating do install (the agent runs that setup). Reword to match the Get Started page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
npx skills update only refreshes and prunes skills already in the lock — it does not discover newly published skills, and its stale-skill prune can silently no-op for shorthand sources (vercel-labs/skills#1376, #591). So the pinned update guidance (mode description, setup prompt, and both pinned state markers) now treats an update as refresh + discover: also run 'npx skills add dfinity/icskills --list' and offer to add any not-yet-installed skills, and remove a renamed skill's stale copy with 'npx skills remove <old>' if it lingers.
Skill Validation ReportNo skill files were changed in this PR — validation skipped. |
This was referenced Jul 30, 2026
Open
raymondk
approved these changes
Aug 4, 2026
raymondk
pushed a commit
to dfinity/examples
that referenced
this pull request
Aug 4, 2026
…icy, dfx-era cleanup (#1465) The dfx→icp-cli migration is complete, so the repo's meta files are rewritten around what matters going forward: - AGENTS.md: trimmed 551→~230 lines. Migration checklist and all version pins removed (versions come from the most recently updated examples); CI section rewritten around the reusable _run-example.yml; new conventions documented: environments are exactly 'local' and 'ic' (the 'ic' name is the ICP Ninja deploy contract), canister:import + --actor-env-alias for inter-canister calls, version-bump scope rule, and the new-example acceptance criteria (from ADDING_AN_EXAMPLE.md). - ICP skills: pinned setup per dfinity/icskills#251 — managed block in AGENTS.md (pinned, ask-to-update), committed skills-lock.json, .agents/skills gitignored (reinstall with npx skills). - Contribution policy: CONTRIBUTING.md rewritten — not accepting external PRs while examples are being restructured to fit the developer docs; issues and forum posts remain welcome. ADDING_AN_EXAMPLE.md deleted (criteria folded into AGENTS.md). - Dead machinery deleted: .ic-commit + its weekly update workflow and the orphaned provision/cache scripts (CI runs in icp-dev-env containers), plus .gitmodules (referenced a long-gone archive/ submodule). - .gitignore hygiene: root file regrouped with comments; dead .dfx/ and _MACOSX entries dropped; stale dfx-era entries removed from three per-example .gitignore files. Lock-file entries unchanged per #1457. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
marc0olo
added a commit
to dfinity/developer-docs
that referenced
this pull request
Aug 5, 2026
## What Aligns the AI-agents docs with the three ways to consume ICP skills. - `docs/guides/ai-coding-agents.md`: adds autosync as a third option, frames fetch-on-demand / pin / auto-update as an explicit choice, corrects the "fetched fresh each time" line to be mode-aware, clarifies that no install is needed to get started (installing is a separate option), and links to the icp-cli-templates `AGENT_SKILLS.md`. - `plugins/astro-agent-docs.mjs`: the generated `llms.txt` "Agent skills" block becomes a short pointer to `skills.internetcomputer.org/llms.txt` instead of duplicating fetch instructions. Em-dash free (docs validator passes); branch up to date with `main`. ## Validation `astro build` passes (209 pages) and `scripts/validate.js` passes on the changed guide. Generated `llms.txt` carries the pointer. _(The `.sources/*` submodule pointers seen in a local working tree are pre-existing and not part of this PR.)_ ### Companion PRs - dfinity/icp-cli-templates#36 - dfinity/icskills#251 - dfinity/icp-cli#673 --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
marc0olo
added a commit
to dfinity/examples
that referenced
this pull request
Aug 6, 2026
* chore: switch ICP skills from pinned to autosync Pinned mode required committing skills-lock.json every time a skill changed. Autosync (dfinity/icskills#251, hardened by #257) keeps skills current with zero commits: a SessionStart hook runs a differential, hash-keyed mirror into .claude/skills/ each session, downloading only changed skills and pruning removed ones. - Add .claude/sync-ic-skills.sh (fetched verbatim from the published autosync skill) and a .claude/settings.json SessionStart hook — both committed so the whole team gets auto-updating skills. - .gitignore: skills now live in .claude/skills/ (ignored — a managed cache); ignore .claude/settings.local.json; drop the .agents/skills line. - Remove committed skills-lock.json (pinned artifact, no longer used). - AGENTS.md: managed block → autosync state; add an on-demand fallback note for non–Claude Code agents (the hook is Claude Code-only). Skills aren't build inputs (CI runs in containers and never touches them), so losing pinned reproducibility has no CI impact; always-latest matches the repo's stay-current philosophy. * docs(AGENTS): explain the autosync skills setup + link the AI-agents guide Add a human-readable note on how skills are wired in this repo (autosync SessionStart hook, nothing to commit on change, Claude Code-only with an on-demand fallback for other agents) and point to the developer-docs AI coding agents guide for general background. * docs(README): brief human-facing pointer to the AI-agents skills setup Explain, for developers cloning the repo, that it works with AI coding agents via ICP skills and uses autosync (a Claude Code SessionStart hook) — so the first-session trust prompt is expected. Keep the detail in AGENTS.md (single source of truth) and link there + the AI coding agents guide. * docs(README): point 'ICP skills' at the registry, not the how-to guide skills.internetcomputer.org is where the skills live and are explored; the docs guide is the how-agents-use-them reference. Link both distinctly instead of hiding the registry behind the guide URL. * docs: link 'autosync' to the autosync-ic-skills skill page autosync is itself an ICP skill that sets up the sync mechanism; link the term to its page (skills.internetcomputer.org/skills/autosync-ic-skills) in both the README and the AGENTS.md setup note. Managed block untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
llms.txtguides the user into a skills-mode choice, and the site no longer duplicatesAGENTS.md.src/pages/llms.txt.ts: leads with the on-demand fetch mechanics (usable immediately, never blocked), then offers a one-time choice (on-demand / pinned / autosync) with an ask-first, non-destructive option to persist it intoAGENTS.md(create if missing; append a delimited block to an unrelated one without touching its content)./AGENTS.mdendpoint (src/pages/AGENTS.md.ts) and reworked the Get Started page by intent (use skills with your agent; start a new project with icp-cli; pin into an existing project; browse/read yourself).llms.txtis now the sole agent entrypoint; no AGENTS.md copy remains on the site.README.md: quick-start paste prompt.Key properties
.well-knownindex andSKILL.mdare plain URL fetches, so web-only agents (e.g. Perplexity) are handled; a correctcurl -sLexample is included. Installs for pin/autosync are run by the agent per the chosen mode.SKILL.mdper task.Validation
astro buildpasses (30 pages); generatedllms.txtcarries the choice-flow and the/AGENTS.mdendpoint is correctly gone. Behaviour validated via simulated paste-flow (empty / unrelated-AGENTS / non-interactive), cross-link arrival, no-re-onboard regression, and pinned/ask-first (interactive offer, non-interactive skip).Companion PRs