Load build-plugin reference content on demand#49
Conversation
The build-plugin SKILL.md was a monolithic ~850-line file loaded in full on every invocation, including auth patterns, field types, pagination options, and viz configs irrelevant to the current phase. This refactors it into a 113-line orchestrator that references six topic-specific files under references/; Claude reads each file only when it reaches the corresponding build phase. A standalone deploy-plugin skill is extracted so validate/deploy/versioning can be invoked independently of the full build flow. Follows Anthropic's recommended progressive disclosure pattern for large skills, which advises keeping SKILL.md under 500 lines. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — progressive-disclosure refactor of the build-plugin skill; no plugin code touched and the one nit found is already posted inline.
Extended reasoning...
Overview
This PR refactors the .claude/skills/build-plugin/SKILL.md orchestrator from ~1419 lines into a 156-line entry point plus six topic-specific reference files (metadata, ui, index-defs, data-streams, oob-content, common-patterns) loaded on demand per build phase. It also extracts a standalone deploy-plugin skill. Pure documentation/skill-content reshuffle — no plugin code, no shipping artefacts, no CI workflow, no source under plugins/ is modified.
Security risks
None. The diff touches only Claude skill markdown files. There are no secrets, no executable changes, no auth or permissions surface, and no third-party content fetched. The bug-hunter flagged that allowEncryption: true was dropped from the key-value example — that is a documentation completeness nit (future agents authoring per-row header secrets lose discoverability), not a runtime security regression.
Level of scrutiny
Low. This affects only how Claude itself navigates skill content; it does not change any plugin behaviour, validator output, or user-facing artefacts. The repo-specific REVIEW.md rules around versioning, metadata.json, ui.json, data streams, etc. don't apply (no plugin directory modified — confirmed by the plugin-pr-summary bot). Content has been preserved structurally; spot-checks show shapes/roles/auth patterns/paging examples carried over intact into the topic files.
Other factors
The single nit (missing allowEncryption) is already an inline comment, severity-tagged as a nit by the bug hunters. Restating it in a review body would just be noise. The refactor is mechanical, follows Anthropic's recommended progressive-disclosure pattern, and the orchestrator clearly directs the reader to each reference file from the checklist and phase tables.
| **`key-value`** — list of key/value pairs (useful for custom headers, tags). | ||
|
|
||
| ```json | ||
| { | ||
| "type": "key-value", | ||
| "name": "headers", | ||
| "label": "Headers" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🟡 The refactored key-value field example in references/ui.md drops "allowEncryption": true from the original SKILL.md, and allowEncryption is no longer mentioned anywhere in the skill. Since key-value is documented as the field type for custom headers (which commonly carry bearer tokens / API keys), this removes the only documented way for authors to mark those values as encrypted. Consider restoring "allowEncryption": true to the example.
Extended reasoning...
What the bug is
The original SKILL.md key-value field example was:
{ "type": "key-value", "name": "headers", "label": "Headers", "allowEncryption": true }The refactored references/ui.md (lines 176-184) trims this to:
{ "type": "key-value", "name": "headers", "label": "Headers" }A repo-wide search for allowEncryption returns zero hits — it is not referenced in any of the new reference files (ui.md, metadata.md, data-streams.md, oob-content.md, index-defs.md, common-patterns.md) or in the slimmed SKILL.md. The original SKILL.md password field description also contained the parenthetical 'preferred over text + allowEncryption', which has been dropped from the new ui.md password entry too.
Why this is a regression, not just trimming
The PR's stated intent is progressive disclosure — splitting a 1419-line SKILL.md into a 156-line orchestrator plus topic-specific references. The goal is to load reference content on demand, not to remove options. Other field-type options (isMulti, allowCustomValues, isClearable, displayAs: fieldGroupToggle, tileEditorStep, visible) were all preserved in the refactor. allowEncryption is the only one that fell out.
It matters for key-value specifically because:
- The skill's own example names the field
headersand labels itHeaders— a strong signal that the canonical use case is custom HTTP headers. - Custom headers very commonly carry
Authorization: Bearer <token>orX-API-Key: <key>values that should be encrypted at rest. - The
passwordfield type (which the refactor still recommends for secrets) cannot be used inside a key-value list — it's a single-value input. So the original SKILL.md guidance 'usepassword(preferred overtext+allowEncryption)' is specifically about scalar fields. For per-row secrets in a key-value list,allowEncryptionis the documented mechanism, and there is no documented substitute.
Step-by-step proof
Imagine a future agent following this skill to build a plugin for an API that requires custom auth headers (very common — Datadog DD-API-KEY, GitHub Authorization, etc.):
- Agent reaches Phase 4 and reads references/ui.md per the SKILL.md instructions.
- Agent needs a config field for arbitrary HTTP headers — finds the
key-valueexample, which is literally labelled 'Headers'. - Agent copies the example:
{ "type": "key-value", "name": "headers", "label": "Headers" }. - Token values typed by users into the headers list are stored unencrypted in plugin config.
- Agent has no way of knowing
allowEncryptionexists, because nothing in the skill mentions it.
The agent could in principle fetch ui.schema.json from the schema URL listed in common-patterns.md, but the skill's design pattern is that example snippets are the source of truth for common usage — schemas are described as 'for resolving specific ambiguities', not as the primary discovery path.
Addressing the refutation
One verifier argued this is acceptable documentation trimming because (a) progressive disclosure is the PR's goal, (b) allowEncryption isn't used in any current in-repo plugin, and (c) the schema URL is preserved for discovery.
These points are fair but don't override the regression:
- Progressive disclosure means moving content to topic files that are loaded on demand, not deleting content. The refactor did expand on
key-value(added it to the dedicated 'Advanced inputs' section of ui.md) — the only thing dropped was this one property. - Not used in-repo today isn't the standard for skill content. The skill is consumed by future agents building new plugins, and the
headers-named example explicitly anticipates per-header credentials. - Schema URL discovery is the fallback path the skill itself reserves for ambiguity resolution, not for discovering core options on common field types.
The refutation also notes this is a duplicate of bug_007 — that's consistent with the synthesis agent's merging.
How to fix
Single one-token change to references/ui.md:
{ "type": "key-value", "name": "headers", "label": "Headers", "allowEncryption": true }Optionally also add a short note adjacent to the example explaining that allowEncryption: true lets users mark per-row values as encrypted — useful for headers that carry tokens.
Severity
nit — this is a skill documentation file, not production code. The platform feature presumably still works; this just makes it harder for a future agent to discover. All three confirming verifiers also assessed this as nit-level.
| | **Author handle** (GitHub handle or display name) | Before writing `metadata.json` (Phase 4) | Goes into `author.name`. Guessing from git config frequently picks the wrong identity. | | ||
|
|
||
| If the user has already volunteered the answer earlier in the conversation, use that and skip the prompt. Otherwise, ask — even in autonomous mode. | ||
| Ask even in autonomous mode — this is required data baked into git history, not a clarifying question. |
There was a problem hiding this comment.
required data baked into git history
What do you mean by this?
There was a problem hiding this comment.
Have reverted, does not matter, likely from old skill edit
|
Any changes in the way you need to trigger/prompt the skill that we should let folk know about? e.g. does deploy have to be triggered separately now? |
Deploy still gets run as part of the main skill, skills can call other skills. Just allows a user to call /deploy-plugin or seperately. Information on deployment is only loaded into context at point it's needed now. |
🧩 Plugin PR Summaryℹ️ No plugins were modified in this PR. |
|
All good from me then |
2 participants
📋 Summary
The build-plugin SKILL.md was a monolithic ~850-line file loaded in full on every invocation, including auth patterns, field types, pagination options, and viz configs irrelevant to the current phase.
This refactors it into a 113-line orchestrator that references six topic-specific files under references/; Claude reads each file only when it reaches the corresponding build phase. A standalone deploy-plugin skill is extracted so validate/deploy/versioning can be invoked independently of the full build flow.
Follows Anthropic's recommended progressive disclosure pattern for large skills, which advises keeping SKILL.md under 500 lines.
🔍 Scope of change
📚 Checklist