Add the penpot skill and extension to the repo root README #216

New issue

Closed

opened 2026-09-14 23:15:29 +00:00 by david · 1 comment

david commented

2026-09-14 23:15:29 +00:00

Owner

Summary

Update the repo root README.md for the new penpot capability: add the penpot skill to the skills table (14 → 15), add the penpot extension to the extensions table (8 → 9), document the PENPOT_URL/PENPOT_TOKEN prerequisites and the pinned Penpot version, and fix every other count or claim that mentions the old numbers.

Background

Depends on: #213, #206

The root README is the package's front page and it makes counted claims — "Skills (14, markdown-only, zero dependencies)", "Extensions (8)", and an install-verification line that tells the reader to check /skills lists the 14 skills. Adding a skill and an extension makes three of those statements wrong, and a stale count is the kind of error that undermines the rest of the page.

This step is labeled documentation, which per AGENTS.md is a no-issue, date-driven change: no separate tracking issue, and the branch/commit/PR follow the documentation/<YYYY-MM-DD>/<slug> form rather than an issue-number form. This issue is the work item, and its own delivery follows AGENTS.md for whichever label it carries.

What must be documented about penpot, precisely:

The skill is not markdown-only in the "zero dependencies" sense of the other skills: it ships a vendored reference under skills/penpot/docs/ and an asset (skills/penpot/assets/*.penpot). Say so rather than silently contradicting the column's claim.
The extension needs PENPOT_URL (instance base URL, no /api suffix) and PENPOT_TOKEN (personal access token), and its RPC API is internal and unversioned — the vendored docs are pinned to a specific Penpot version, which is a prerequisite worth stating.

Documentation Required

A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting.

docs/reference/penpot-api/

https://help.penpot.app/technical-guide/integration/ — the access-token model and the base-URL shape, so the prerequisite text is accurate (including the "no /api suffix" rule and that Authorization: Token is used rather than Bearer).
https://help.penpot.app/technical-guide/configuration/ — how a Penpot version is identified, so the "vendored docs are pinned to version X" sentence can be checked against the running instance.
https://help.penpot.app/user-guide/design-systems/libraries/ — one line of context for the extension's library import/link behaviour, if the README row mentions it.

docs/reference/pi-coding-agent/

https://pi.dev/docs/latest/packages — how the package manifest and install flow work, so the README's install section (and the /skills count claim) is updated consistently.

Implementation Details

Edit the root README.md only. Locate the current text first, since the numbers appear in more than one place:

grep -n "14\|8)\|Skills\|Extensions" README.md | head -40

Skills table. Change the heading claim from 14 to 15 and add a row for penpot in the existing format, e.g.:

| penpot | Create Penpot designs from a DESIGN.md, a prompt, an SVG or a screenshot — bootstrap library tokens, compose screens with the penpot extension, and instance library components. Ships a vendored Penpot reference pinned to one version. |

Wording must make the extension dependency and the vendored reference clear, matching the level of detail of the neighbouring rows (some of which name their extension).
Extensions table. Change 8 to 9 and add:

| penpot | Penpot design tools: colour/typography assets, staged changesets with a single-call commit, frames/rects/text/images with auto-layout, .penpot library import-export, component instancing, SVG import, and a designated-target write guard (calls the RPC API directly with PENPOT_URL/PENPOT_TOKEN) |

Keep the cell to the same approximate length and style as the others.
Prerequisites section. Add a penpot bullet covering: PENPOT_URL (base URL, no /api) and PENPOT_TOKEN (account settings → access tokens); that the token needs edit rights on a project to write; and the Penpot version the vendored docs are pinned to (state the version actually used, e.g. 2.17, plus where it is recorded — skills/penpot/docs/VERSION).
Install-verification line. Update any "check /skills lists the 14 skills" wording to 15, and check whether the extension list is repeated anywhere else in the file.
Do not change unrelated content, and do not renumber or reformat existing table rows beyond what is required.

Acceptance Criteria

The skills table heading says 15 and contains a penpot row that names the skill's purpose and its relationship to the penpot extension and the vendored docs.
The extensions table heading says 9 and contains a penpot row describing the tool family and the required environment variables.
The Prerequisites section documents PENPOT_URL (no /api suffix), PENPOT_TOKEN, the need for edit rights to write, and the pinned Penpot version with a pointer to where it is recorded.
Every remaining occurrence of the old counts (14 skills / 8 extensions) is updated — verified by grepping the file.
No other content in the root README is changed.
Table formatting renders correctly (columns aligned, pipes balanced) and matches the neighbouring rows' style.

Test Plan

# 1. No stale counts remain
grep -n "14 skills\|extensions (8\|(14)\|(8)" README.md || echo "no stale counts"

# 2. New rows present
grep -n "penpot" README.md

# 3. Rendering sanity — confirm the tables still parse
grep -c "^| " README.md

Then open the README in a markdown preview (or gh/Forgejo's rendered view) and confirm both tables render with the new rows in place and the columns intact.

## Summary Update the repo root `README.md` for the new penpot capability: add the `penpot` skill to the skills table (14 → 15), add the `penpot` extension to the extensions table (8 → 9), document the `PENPOT_URL`/`PENPOT_TOKEN` prerequisites and the pinned Penpot version, and fix every other count or claim that mentions the old numbers. ## Background **Depends on:** #213, #206 The root README is the package's front page and it makes **counted** claims — "Skills (14, markdown-only, zero dependencies)", "Extensions (8)", and an install-verification line that tells the reader to check `/skills` lists the 14 skills. Adding a skill and an extension makes three of those statements wrong, and a stale count is the kind of error that undermines the rest of the page. This step is labeled `documentation`, which per `AGENTS.md` is a **no-issue, date-driven** change: no separate tracking issue, and the branch/commit/PR follow the `documentation/<YYYY-MM-DD>/<slug>` form rather than an issue-number form. This issue *is* the work item, and its own delivery follows AGENTS.md for whichever label it carries. What must be documented about penpot, precisely: - The skill is **not** markdown-only in the "zero dependencies" sense of the other skills: it ships a vendored reference under `skills/penpot/docs/` and an asset (`skills/penpot/assets/*.penpot`). Say so rather than silently contradicting the column's claim. - The extension needs `PENPOT_URL` (instance base URL, **no** `/api` suffix) and `PENPOT_TOKEN` (personal access token), and its RPC API is internal and unversioned — the vendored docs are pinned to a specific Penpot version, which is a prerequisite worth stating. ## Documentation Required A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting. **`docs/reference/penpot-api/`** - https://help.penpot.app/technical-guide/integration/ — the access-token model and the base-URL shape, so the prerequisite text is accurate (including the "no `/api` suffix" rule and that `Authorization: Token` is used rather than `Bearer`). - https://help.penpot.app/technical-guide/configuration/ — how a Penpot version is identified, so the "vendored docs are pinned to version X" sentence can be checked against the running instance. - https://help.penpot.app/user-guide/design-systems/libraries/ — one line of context for the extension's library import/link behaviour, if the README row mentions it. **`docs/reference/pi-coding-agent/`** - https://pi.dev/docs/latest/packages — how the package manifest and install flow work, so the README's install section (and the `/skills` count claim) is updated consistently. ## Implementation Details Edit the root `README.md` only. Locate the current text first, since the numbers appear in more than one place: ```bash grep -n "14\|8)\|Skills\|Extensions" README.md | head -40 ``` 1. **Skills table.** Change the heading claim from 14 to 15 and add a row for `penpot` in the existing format, e.g.: | `penpot` | Create Penpot designs from a `DESIGN.md`, a prompt, an SVG or a screenshot — bootstrap library tokens, compose screens with the `penpot` extension, and instance library components. Ships a vendored Penpot reference pinned to one version. | Wording must make the extension dependency and the vendored reference clear, matching the level of detail of the neighbouring rows (some of which name their extension). 2. **Extensions table.** Change 8 to 9 and add: | `penpot` | Penpot design tools: colour/typography assets, staged changesets with a single-call commit, frames/rects/text/images with auto-layout, `.penpot` library import-export, component instancing, SVG import, and a designated-target write guard (calls the RPC API directly with `PENPOT_URL`/`PENPOT_TOKEN`) | Keep the cell to the same approximate length and style as the others. 3. **Prerequisites section.** Add a `penpot` bullet covering: `PENPOT_URL` (base URL, no `/api`) and `PENPOT_TOKEN` (account settings → access tokens); that the token needs **edit** rights on a project to write; and the Penpot version the vendored docs are pinned to (state the version actually used, e.g. 2.17, plus where it is recorded — `skills/penpot/docs/VERSION`). 4. **Install-verification line.** Update any "check `/skills` lists the 14 skills" wording to 15, and check whether the extension list is repeated anywhere else in the file. 5. **Do not change** unrelated content, and do not renumber or reformat existing table rows beyond what is required. ## Acceptance Criteria - [ ] The skills table heading says 15 and contains a `penpot` row that names the skill's purpose and its relationship to the `penpot` extension and the vendored docs. - [ ] The extensions table heading says 9 and contains a `penpot` row describing the tool family and the required environment variables. - [ ] The Prerequisites section documents `PENPOT_URL` (no `/api` suffix), `PENPOT_TOKEN`, the need for edit rights to write, and the pinned Penpot version with a pointer to where it is recorded. - [ ] Every remaining occurrence of the old counts (14 skills / 8 extensions) is updated — verified by grepping the file. - [ ] No other content in the root README is changed. - [ ] Table formatting renders correctly (columns aligned, pipes balanced) and matches the neighbouring rows' style. ## Test Plan ```bash # 1. No stale counts remain grep -n "14 skills\|extensions (8\|(14)\|(8)" README.md || echo "no stale counts" # 2. New rows present grep -n "penpot" README.md # 3. Rendering sanity — confirm the tables still parse grep -c "^| " README.md ``` Then open the README in a markdown preview (or `gh`/Forgejo's rendered view) and confirm both tables render with the new rows in place and the columns intact.

david added this to the Penpot: M9 - README and rollout milestone

2026-09-14 23:15:29 +00:00

david added the

documentation

label

2026-09-14 23:15:29 +00:00

david referenced this issue from a pull request that will close it,

2026-09-15 08:50:12 +00:00

issue-216: Add the penpot skill and extension to the repo root README #250

david closed this issue

2026-09-15 08:50:13 +00:00

david commented