Skills
Install Bloques agent skills so your coding agent knows how to do Bloques work.
A skill is a folder of instructions your coding agent loads when the task matches: no pasted context, no re-explaining. Bloques publishes its skills in the bloques repository, under skills/. Claude Code, Cursor, Codex, and other agents read the same folder.
Install a skill once in the repository behind your Bloques site, commit it, and everyone working in that repository gets the same instructions.
Install a skill
Run this from the root of your docs repository:
npx skills add edgarlr/bloquesThe installer lists the skills it finds and asks which agents to set them up for. To preselect one skill, name it:
npx skills add edgarlr/bloques -s bloques-update-docsNeither command runs unattended: the installer asks before it writes. Add -y to take its defaults: the agents already on the machine, installed for the project.
Either command writes two things:
- The skill folder, in
.agents/skills/bloques-update-docs, plus a symlink to it from the directory each agent reads, for example.claude/skills/bloques-update-docsfor Claude Code. skills-lock.json, which records the source and content hash of every installed skill.
Commit both. Teammates and scheduled runs then load the identical instructions instead of whatever their agent last downloaded. Refresh later with npx skills update, and review the diff: a skill update changes what your agent does.
A skill runs with your agent's permissions, including its file writes and
shell commands. Read SKILL.md before the first run, the same as any
dependency you add to a repository.
bloques-update-docs
Docs drift the moment a button gets renamed or a default changes. The skill reads recently merged pull requests in your product repository, corrects the statements those changes made false, and opens a pull request against your docs.
It needs the GitHub command-line tool (gh), signed in to an account that reads both repositories, since it pulls merged pull requests and their diffs through it. Check with gh auth status.
Point it at your product
Name your product repository in owner/name form in the prompt, or record it once in AGENTS.md at the root of your docs repository:
Product repo: acme/acme-appWith neither, the skill asks instead of guessing.
Run an audit
From your docs repository, ask your agent to sync the docs:
Sync the docs with acme/acme-app. Audit the last 14 days.Without a window, the skill audits pull requests merged in the last 7 days. It then:
- Splits user-facing changes from refactors, dependency bumps, and test-only work.
- Reads each user-facing diff and confirms the behavior against the product's current code.
- Edits your
.mdxpages anddocs.jsononly where a change made a statement false. - Checks that
docs.jsonparses and every navigation entry resolves to a real file. - Commits to a
docs-sync/<date>branch and opens a pull request pairing each edit with the product pull request that caused it.
A quiet window ends with no branch, no commit, and no pull request. The skill reports what it audited and why your pages still hold. Weekly runs keep each audit small, so point a scheduled agent run or a cron job at the same prompt you'd type by hand.
What it fixes and what it leaves
| Fixes | Leaves alone |
|---|---|
| Behavior that changed or no longer exists | Phrasing, tone, and structure |
| A list of options, values, or steps with a missing, extra, or renamed entry | A whole feature with no page yet |
| A default value that changed | Navigation, theme, and frontmatter that state nothing false |
| A renamed field, flag, environment variable, button, or menu item | Anything unconfirmable against the product's current code |
| Steps that no longer match the real flow | Pages the window's changes didn't touch |
The skill corrects facts. It never writes new pages. When a change ships a feature your docs don't cover, the pull request body names the gap. Treat those lines as your writing queue.
Review the pull request the way you'd read any other. Every edit traces to one merged product pull request named in the body, so open that pull request whenever an edit looks wrong. Merging into your default branch deploys the site.
Troubleshooting
The agent doesn't use the skill. Name it in the prompt (for example, "use the bloques-update-docs skill") and confirm the folder sits in the skills directory your agent reads.
The audit finds no pull requests. Widen the window, then check gh auth status. A private product repository needs an account with read access to it.
An edit contradicts the rest of the page. The skill fixes sentences, not page structure. Close the pull request, fix the page yourself, and rerun the audit.