Skip to content

docs(plugins): state how a skill names another plugin's skill - #345

Merged
0xA3B merged 2 commits into
mainfrom
docs/inter-plugin-requirements
Nov 16, 2026
Merged

0xA3B merged 2 commits into
mainfrom
docs/inter-plugin-requirements

Conversation

@0xA3B

@0xA3B 0xA3B commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Each plugin installs alone, but no rule said how a skill should name a skill of another plugin. Each
skill settled the question by itself. The reason git:babysit-pr stops without the engineering
plugin while git:create-pr continues was not written down, and a planned git:ship skill needs
that rule before it takes a requirement on engineering.

This change adds a "Requirements between plugins" section to plugins/AGENTS.md. An instruction
that applies a skill of another plugin takes one of two forms:

  • Soft requirement, the default. The instruction is conditioned on the other skill being
    available, and the work continues without it. When the report would otherwise imply the skipped
    work happened, the applying skill states the fallback and reports the omission.
  • Hard requirement. The applying skill confirms the other plugin is available before its first
    side effect, and stops with the plugin to install when it is absent. One check covers every skill
    of that plugin.

The choice depends on the fallback, not on invocation policy. A hard requirement applies only when,
without the other skill, the applying skill would take a side effect outside the checkout on a
decision the other skill supplies. A skill applied only to wording always has a safe fallback. The
rule could not depend on invocation policy, because babysit-pr is implicitly invokable and its
hard requirement is justified.

Existing references

I checked every instruction in plugins/ that applies another plugin's skill against the policy.
One did not comply: engineering/references/COMMENTS.md applied writing:technical-writing with no
condition. It now applies the skill when that skill is available, and engineering moves to 3.3.1.

The two terms are defined in the policy section and are not added to the ubiquitous language
section, so each has one definition.

Each plugin installs alone, but the instruction files gave no rule for
an instruction that applies a skill of another plugin. Skills settled it
one at a time, and the reason babysit-pr stops without the engineering
plugin while create-pr continues was written nowhere.

The policy names the two forms, soft requirement and hard requirement,
and chooses between them by whether a safe fallback exists.
…ilable

The comment rules applied writing:technical-writing with no condition,
so a session without the writing plugin had an instruction it could not
follow.
Copilot AI lite review requested due to automatic review settings November 16, 2026 04:39
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T04:39:55.190270Z a927cd6 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The reviewed documentation and aligned plugin version updates have no remaining active issues identified.

No open issues 🎉

What changed in this PR

Documents how skills should depend on skills from separately installed plugins, distinguishing soft requirements with fallbacks from hard requirements that must be checked before side effects. It also updates the engineering plugin version.

Changes:

  • Adds cross-plugin soft- and hard-requirement guidance to plugins/AGENTS.md.
  • Updates the engineering comments reference to conditionally use the technical-writing skill.
  • Bumps the engineering plugin version to 3.3.1 in both manifests.
File Description
plugins/​engineering/​references/​COMMENTS.md Updates the comments guidance to conditionally reference the technical-writing skill.
plugins/​engineering/​plugin.json Bumps the portable engineering plugin version to 3.3.1.
plugins/​engineering/​.claude-plugin/​plugin.json Keeps the Claude extension manifest aligned at version 3.3.1.
plugins/​AGENTS.md Defines soft and hard requirements for skills that depend on skills from other plugins.

Review effort: Lite

@0xA3B
0xA3B merged commit a61b9ac into main Nov 16, 2026
2 checks passed
@0xA3B
0xA3B deleted the docs/inter-plugin-requirements branch November 16, 2026 04:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants