Update build-plugin skill's readme template#98
Conversation
🧩 Plugin PR Summaryℹ️ No plugins were modified in this PR. |
📝 WalkthroughWalkthroughThe build-plugin skill is updated to version 0.0.12 and now defines a two-phase README process. A new reference template specifies structure, writing rules, an example, and a Phase 9 completion checklist before deployment. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/build-plugin/references/readme.md:
- Around line 143-144: Extend the README completion checklist entry for Known
limitations to explicitly require user-facing documentation of authentication
quirks, permission constraints, data freshness, and read-only behavior,
alongside the existing timeframe, payload, import-count, and rate-limit
constraints.
In @.claude/skills/build-plugin/SKILL.md:
- Around line 317-321: Update the Phase 9 workflow to require the README
completion checklist to pass in full and obtain explicit approval before
invoking deploy-plugin. Ensure deploy-plugin’s validation also passes before
deployment or re-indexing, and prevent any tenant-affecting change when either
the checklist, validation, or approval gate fails.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro
Run ID: 781f06ee-0b55-4c5b-b199-84695f933023
📒 Files selected for processing (2)
.claude/skills/build-plugin/SKILL.md.claude/skills/build-plugin/references/readme.md
| - [ ] Every constraint that forced a Phase 5–6 fix (restricted `timeframes`, payload caps, import caps, rate limits) appears in **Known limitations** in user-facing words. | ||
| - [ ] No `<!-- finalized in Phase 9 -->` placeholders remain. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Extend the checklist to cover all required limitation categories.
The template requires documenting authentication quirks, permission constraints, freshness, and read-only behavior, but this checklist only names timeframe, payload, import-count, and rate-limit constraints. A README can therefore pass the checklist while still omitting required user-facing limitations.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/build-plugin/references/readme.md around lines 143 - 144,
Extend the README completion checklist entry for Known limitations to explicitly
require user-facing documentation of authentication quirks, permission
constraints, data freshness, and read-only behavior, alongside the existing
timeframe, payload, import-count, and rate-limit constraints.
| ## Phase 9: Finalize README, validate & deploy | ||
|
|
||
| **Finalize `docs/README.md` first** — complete the placeholder sections (What this plugin monitors, Data streams, What gets indexed, Known limitations) and run the completion checklist in [readme.md](references/readme.md). Source Known limitations from the reconciliation passes' API-level discoveries: every constraint that forced a fix in Phases 5–6 belongs there in user-facing words. | ||
|
|
||
| Invoke the `deploy-plugin` skill for the final validate, version bump, and deploy. | ||
| Then invoke the `deploy-plugin` skill for the final validate, version bump, and deploy. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the referenced skill and related deployment instructions.
fd -a "SKILL.md" .claude/skills | sed -n '1,120p'
printf '\n---\n'
fd -a "readme.md" .claude/skills | sed -n '1,120p'
printf '\n---\n'
# Show the relevant section around the cited lines.
python3 - <<'PY'
from pathlib import Path
p = Path('.claude/skills/build-plugin/SKILL.md')
lines = p.read_text().splitlines()
for start,end in [(300,340)]:
for i in range(start-1, min(end, len(lines))):
print(f"{i+1}: {lines[i]}")
PYRepository: squaredup/plugins
Length of output: 3015
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find deploy-plugin skill and inspect its user-confirmation / validation behavior.
fd -a "deploy-plugin" .claude/skills
printf '\n---\n'
rg -n "confirm|confirmation|checklist|validate|deploy|re-index|reindex|version bump|stop|fail" .claude/skills/build-plugin .claude/skills/deploy-plugin -SRepository: squaredup/plugins
Length of output: 33966
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the deploy-plugin skill and any confirmation requirements.
fd -a "SKILL.md" .claude/skills/deploy-plugin
printf '\n---\n'
python3 - <<'PY'
from pathlib import Path
for path in [Path('.claude/skills/deploy-plugin/SKILL.md')]:
if path.exists():
lines = path.read_text().splitlines()
print(f"FILE: {path}")
for i,l in enumerate(lines,1):
if any(k in l.lower() for k in ["confirm", "confirmation", "checklist", "validate", "deploy", "re-index", "reindex", "version bump", "stop", "fail"]):
print(f"{i}: {l}")
PYRepository: squaredup/plugins
Length of output: 2648
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path('.claude/skills/build-plugin/references/readme.md')
lines = p.read_text().splitlines()
for start,end in [(136,220)]:
for i in range(start-1, min(end, len(lines))):
print(f"{i+1}: {lines[i]}")
PYRepository: squaredup/plugins
Length of output: 832
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path('.claude/skills/build-plugin/references/readme.md')
lines = p.read_text().splitlines()
for i,l in enumerate(lines,1):
if 136 <= i <= 220:
print(f"{i}: {l}")
PYRepository: squaredup/plugins
Length of output: 832
Gate the final deploy and re-index on a passing checklist and explicit approval.
Phase 9 only says to run the README checklist before invoking deploy-plugin; it doesn’t require every item to pass, and deploy-plugin only validates before deploying. Make both steps hard gates before any tenant-affecting change.
🧰 Tools
🪛 SkillSpector (2.3.11)
[warning] 269: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.
Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.
(Excessive Agency (EA2))
[warning] 32: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.
Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.
(Memory Poisoning (MP2))
[warning] 32: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries.
Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content.
(Memory Poisoning (MP2))
[warning] 42: [RA2] Session Persistence: Skill establishes unauthorized persistence across sessions via cron jobs, startup scripts, or state files. Session persistence allows an attacker to maintain access beyond the current interaction.
Remediation: Remove any persistence mechanisms (cron jobs, startup scripts, state files). Skills should not maintain state across sessions without explicit user consent.
(Rogue Agent (RA2))
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/build-plugin/SKILL.md around lines 317 - 321, Update the
Phase 9 workflow to require the README completion checklist to pass in full and
obtain explicit approval before invoking deploy-plugin. Ensure deploy-plugin’s
validation also passes before deployment or re-indexing, and prevent any
tenant-affecting change when either the checklist, validation, or approval gate
fails.
Source: Linters/SAST tools
|
This looks great - fancy raising a subsequent PR that makes all the existing plugins follow this spec? |
2 participants
📋 Summary
The readme generated by the skill, could do with some order changes as noted in a lot of the PRs.
The old structure
This led to sections like
This could mean there was a lot of text before it gave guidance on actually setting up the plugin, unlike our docs site where it normally shows a short paragraph and goes straight into setup.
i.e. https://docs.squaredup.com/data-sources/jira-plugin
The new structure
🔍 Scope of change
📚 Checklist