chore(skills): audit skill suite against doctor checks and forge conventions - #44
Merged
Conversation
phase-execution.md, pattern-audit.md, and forge-scout.md were consumed by forge-ship (and forge-scout by forge-implement) while living in forge-implement's private directories — violating the self-containment rule. Also drops the Refs # trailer convention stated nowhere else and removes stale step/dimension references from pattern-audit. Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
Reflection described the removed four-reviewer design; Composite skill claimed pure orchestration; Issue claimed an unpersisted AFK/HITL field and a priority no skill uses; quality gates omitted coverage. Adds Vertical phase and Tiny diff (both cross-skill and load-bearing), removes Smart/Dumb zone and Three-tier context per the file's own single-consumer rule — they live in architecture.md and setup-project. Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
- reflect: drop context: fork (forking the whole skill strands the interactive triage step; fresh context already comes from the (delegate) review step), rename Triage Deferred Items to Triage Findings — items only become deferred as the outcome of triage - implement: document --unattended, fold Sub-Issue Handling into Step 1, action-verb step titles, placeholder casing, disambiguate from ship in the description - ship: bash example for push/PR, coverage fallback, Format and Coverage rows in the output gates, scout delegation fallback - create-issue/shape: complete allowed-tools their own steps require; create-issue gains trailing-context support and records the AFK/HITL mode in the Issue body - address-pr-feedback: Follow-up renamed to Deferred item (canonical) - issue-operations: new label discovery/update and epic sub-issue sections absorb the provider conditionals skills had inlined; sub-issue linking uses task lists with --parent as opt-in (the flag is not available on all gh versions) Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
The Cross-Skill Consistency table's Referenced In column predated forge-ship's extraction from implement and missed it in ~8 rows; the architecture tree omitted the three most-consumed _shared files and listed directories that no longer exist; testing/development check lists enumerated only 5 of 7 skills; README counted six skills; the architecture Operating Constraints table said ~150-200 instructions per skill where coding-guidelines says under ~35. Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
The review caught contradictions introduced while syncing the consistency table (trailing-context and vertical-slices rows over-claimed; README/AGENTS/architecture still scoped trailing context to structured-input skills), plus pre-existing defects the renames exposed: reflect reported before triaging, ship's Step 2 delegate lacked its Inputs/Expected blocks, and CONTEXT's Deferred item definition didn't cover review-feedback items. Also documents context: fork in the frontmatter conventions and compresses three-sentence descriptions to two. Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
There was a problem hiding this comment.
Pull request overview
Audits and realigns the Forge skill suite against “doctor” checks and Forge conventions, reducing cross-skill drift by centralizing shared references/roles under skills/_shared/ and updating skill/docs vocabulary and workflows accordingly.
Changes:
- Consolidates cross-skill reference material and roles in
skills/_shared/and updates skill links/usages to match. - Normalizes skill interfaces and flows (trailing context, delegation inputs/outputs, triage/report ordering, naming consistency).
- Refreshes project documentation (architecture, guidelines, development/testing checklists, README, shared vocabulary in
CONTEXT.md).
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/forge-ship/SKILL.md | Updates ship flow (shared references, delegation metadata, quality gates, PR creation guidance). |
| skills/forge-shape/SKILL.md | Expands allowed tools and clarifies wording around facts/questions and optional delegation. |
| skills/forge-setup-project/SKILL.md | Clarifies $ARGUMENTS usage and makes step titles more action-oriented. |
| skills/forge-setup-project/references/output-format.md | Updates recommendations/next-steps wording and points to shape as an alternative. |
| skills/forge-reflect/SKILL.md | Reorders triage/reporting steps and tightens wording around quality gates + findings. |
| skills/forge-implement/SKILL.md | Aligns inputs, unattended mode, shared scout role usage, and action-verb step titles. |
| skills/forge-create-issue/SKILL.md | Completes allowed-tools, adds trailing-context support, and aligns on shared issue-ops guidance. |
| skills/forge-address-pr-feedback/SKILL.md | Adds AskUserQuestion to allowed tools and renames follow-ups to “Deferred” items. |
| skills/_shared/roles/forge-scout.md | Updates scout framing/terminology to match Issue/plan language. |
| skills/_shared/plan-folder-spec.md | Aligns plan-folder body structure terminology with current Issue conventions. |
| skills/_shared/phase-execution.md | Fixes internal shared-linking and removes the unsupported Refs #... commit trailer guidance. |
| skills/_shared/pattern-audit.md | Generalizes audit timing language (implementation/reflection) to match updated skill structure. |
| skills/_shared/issue-operations.md | Adds label discovery/update + epic/sub-issue guidance and provider fallbacks. |
| README.md | Updates skill count and broadens trailing-context statement to all skills. |
| docs/testing.md | Updates consistency-check grep patterns to include the full skill suite and trailing context for all skills. |
| docs/development.md | Simplifies validation grep examples to reflect trailing context support across all skills. |
| docs/coding-guidelines.md | Updates conventions (including context: fork guidance) and shared-role references. |
| docs/architecture.md | Refreshes tree, operating constraints wording, and delegation/composition design decisions. |
| CONTEXT.md | Realigns shared vocabulary (Reflection/Tiny diff/Vertical phase/etc.) and removes obsolete terms. |
| AGENTS.md | Updates “one invocation convention” principle to apply to every skill. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Removing context: fork from forge-reflect meant inline tiny-diff reviews run in the session that may have just written the code — the fork previously gave even those fresh eyes. Rather than always delegating (which would erase the lean-review design), the inline path is now allowed only when the reviewing session did not author the changes. For forge-ship the session always authors the diff, so its review now always delegates. Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
mgratzer
force-pushed
the
chore/skill-suite-audit
branch
from
July 27, 2026 14:19
b48a048 to
0f26ad7
Compare
Applies the current context-engineering guidance for Claude 5 models: prefer judgment over defensive rules, never state the same guidance in two places, and use progressive disclosure for detail. - ship: Step 1 now executes forge-implement's process by reference instead of paraphrasing it as 1a-1g — the duplication had already drifted once; ship's own body drops to ~20 instructions (note: a ship invocation still loads implement's ~35, so the budget is honest per file, not per invocation — recorded in coding-guidelines) - implement: references _shared/phase-execution.md, pattern-audit.md, and deep-modules.md instead of inlining copies; defensive flag-lists become judgment calls with an unattended fallback - setup-project: three-way mode table collapses into one assessment step (file state determines the work); interrogation lists compress to intent; scoring rubric and tier model stay as the skill's opinion - shape/create-issue/reflect: guidelines restating process steps or shared modules deleted; the authoritative statement survives in one place - post-review fixes: implement's clarification step is unattended- aware so ship --unattended cannot block; pr-workflow.md content spec restored; output-format headings match the collapsed flow; the lettered-sub-step rule that invited re-inlining removed; ship's composition described consistently everywhere Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The forge skills had never had a systematic health check, and recent refactors — extracting forge-ship from forge-implement, moving to the
_sharedlayer, the #42 token reduction — left drift behind: cross-skill files stranded in implement's private directories, CONTEXT.md describing removed designs, and a consistency table that predates ship's existence. On top of the audit, this PR applies the current Claude 5 context-engineering guidance (judgment over defensive rules, single-statement guidance, progressive disclosure) to rightsize every skill to the repo's own ~35-instruction budget.The audit ran in three layers: a mechanical checker (frontmatter validity, link integrity,
_sharedconsumer graph), three fresh-context audit agents (instruction budget/structure, shared-layer integrity, vocabulary/descriptions), and verification of every raw finding before fixing. Each substantive commit then got its own fresh-context review pass; confirmed findings were fixed in follow-up commits.Changes
Audit fixes
phase-execution.md,pattern-audit.md, androles/forge-scout.mdintoskills/_shared/; dropped theRefs #trailer stated nowhere elsecontext: fork(forking the whole skill would strand the interactive triage step); triage renamed and reordered before the report--unattended; action-verb step titles; placeholder casing; description disambiguated from shipallowed-toolscompleted to cover their own steps; AFK/HITL mode recorded at creationghversionReview-rule change
context: forkused to provide, on every runtime.Rightsizing (Claude 5 context rules)
_shared/phase-execution.md,pattern-audit.md, anddeep-modules.mdinstead of inlining copies; defensive flag-lists become judgment calls with an unattended fallback (~52 → ~35)Test plan
_sharedconsumer graph: no orphans, no cross-skill links into skill-private directoriesfind skills -type fhttps://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca