diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b5b6c232..eda79958 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -24,7 +24,7 @@ Identify the source and license of any third-party material. Describe any AI ass - [ ] The change is focused and links an accepted proposal when required. - [ ] No file under `Documentation/` is added, edited, moved, renamed, or deleted. - [ ] Every added or changed skill was reviewed with `verifying-skills`. -- [ ] All P1 and P2 verification findings are resolved. +- [ ] All P1 and P2 verification findings are resolved; applicable reports state `P1 findings open: 0` and `P2 findings open: 0`. - [ ] Applicable verification reports under `Verification/` are added or updated. - [ ] Affected AI tool manifests contain valid JSON and the same version. - [ ] The plugin version was incremented when required. diff --git a/.github/scripts/validate-contribution.ps1 b/.github/scripts/validate-contribution.ps1 index 2c24541d..a2894132 100644 --- a/.github/scripts/validate-contribution.ps1 +++ b/.github/scripts/validate-contribution.ps1 @@ -15,6 +15,34 @@ function Add-ValidationError { $script:errors.Add($Message) } +function Test-NoOpenFindings { + param( + [Parameter(Mandatory)] + [string]$ReportText, + + [Parameter(Mandatory)] + [ValidateSet("P1", "P2")] + [string]$Severity + ) + + $escapedSeverity = [regex]::Escape($Severity) + # Prefer the explicit open-count field while keeping existing reports and + # in-flight pull requests compatible with their earlier zero-finding wording. + $acceptedPatterns = @( + "(?im)^\s*(?:[-*]\s+)?(?:\*\*)?$escapedSeverity\s+findings\s+open(?:\*\*)?\s*:\s*0\.?\s*$", + "(?im)^\s*(?:[-*]\s+)?No(?:\s+open)?\s+$escapedSeverity\s+findings\.?\s*$", + "(?im)^\s*(?:[-*]\s+)?All\s+$escapedSeverity\s+findings\s+(?:are|have been)\s+resolved\.?\s*$" + ) + + foreach ($pattern in $acceptedPatterns) { + if ([regex]::IsMatch($ReportText, $pattern)) { + return $true + } + } + + return $false +} + function Get-RepositoryRelativePath { param([string]$Path) $fullPath = [System.IO.Path]::GetFullPath($Path) @@ -207,11 +235,11 @@ foreach ($skillFile in $skillFiles) { } else { $reportText = Get-Content -LiteralPath $reportPath -Raw -Encoding utf8 - if ($reportText -notmatch '(?m)^No P1 findings\.$') { - Add-ValidationError "Verification/$skillName-review.md does not confirm that P1 findings are resolved." + if (-not (Test-NoOpenFindings -ReportText $reportText -Severity "P1")) { + Add-ValidationError "Verification/$skillName-review.md does not confirm that no P1 findings remain open. Add 'P1 findings open: 0' after the P1 heading when all P1 findings are resolved." } - if ($reportText -notmatch '(?m)^No P2 findings\.$') { - Add-ValidationError "Verification/$skillName-review.md does not confirm that P2 findings are resolved." + if (-not (Test-NoOpenFindings -ReportText $reportText -Severity "P2")) { + Add-ValidationError "Verification/$skillName-review.md does not confirm that no P2 findings remain open. Add 'P2 findings open: 0' after the P2 heading when all P2 findings are resolved." } } } diff --git a/.github/skills/distill/SKILL.md b/.github/skills/distill/SKILL.md index 10b7099e..4f4e00e3 100644 --- a/.github/skills/distill/SKILL.md +++ b/.github/skills/distill/SKILL.md @@ -1,6 +1,6 @@ --- name: distill -description: Extract friction patterns from the current conversation into reusable skills. +description: Extracts recurring friction from completed work into reusable skills. Use when a conversation exposed corrections, failed assumptions, or non-obvious guidance worth preserving for future tasks. --- # Distill diff --git a/.github/skills/verifying-skills/SKILL.md b/.github/skills/verifying-skills/SKILL.md index 9d547130..3c2097b7 100644 --- a/.github/skills/verifying-skills/SKILL.md +++ b/.github/skills/verifying-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: verifying-skills -description: Verifies a skill against authoritative skill-authoring guidance and produces a severity-bucketed review report with actionable findings. Use when asked to review a skill, verify a skill, audit a SKILL.md, check skill quality, or validate a skill against best practices. +description: Verifies a skill against four authoritative sources — Best Practices, Skills Docs, Complete Guide, and Skill Creator — and produces a severity-bucketed review report with actionable findings. Use when asked to review a skill, verify a skill, audit a SKILL.md, check skill quality, or validate a skill against best practices. --- # Verify Skills diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 071898b3..7ae2ec64 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,7 +101,7 @@ Plain Markdown prompts and reference files are accepted but discouraged when a d 3. Add only the references, scripts, assets, and agent metadata the skill requires. 4. Verify the skill with the `verifying-skills` skill from `Common/agent-tooling`. 5. Commit the resulting report as `Verification/{skill-name}-review.md`. -6. Resolve all P1 and P2 findings before requesting review. Document any intentionally retained P3 finding in the pull request. +6. Resolve all P1 and P2 findings before requesting review. The report must state `P1 findings open: 0` and `P2 findings open: 0`; clearly labeled closed findings may remain for context. Document any intentionally retained P3 finding in the pull request. 7. Add or update `.github/skills/{skill-name}/SKILL.md` as a GitHub Copilot discovery adapter. Keep its name and description aligned with the canonical skill and link it to the canonical `SKILL.md`; do not duplicate the canonical workflow or resources. 8. Increment the plugin version in its Claude, Cursor, and Codex manifests. 9. Add the skill to the plugin's README. @@ -145,7 +145,7 @@ Before opening a pull request: 1. Confirm that the contribution is based on and targets the latest published Acumatica release branch. 2. Run the `verifying-skills` skill from `Common/agent-tooling` for every added or changed skill. -3. Resolve all P1 and P2 findings. +3. Resolve all P1 and P2 findings and confirm the report states `P1 findings open: 0` and `P2 findings open: 0`. 4. Commit or update the applicable report under `Verification/`. 5. Confirm that local links resolve and referenced files exist. 6. Confirm that all affected plugin manifests contain valid JSON and matching versions. diff --git a/Common/agent-tooling/.claude-plugin/plugin.json b/Common/agent-tooling/.claude-plugin/plugin.json index 89d9b05c..3e2352a4 100644 --- a/Common/agent-tooling/.claude-plugin/plugin.json +++ b/Common/agent-tooling/.claude-plugin/plugin.json @@ -4,5 +4,5 @@ "description": "Tools for authoring and verifying agent skills: friction-pattern extraction and skill quality verification", "author": { "name": "Acumatica" }, "license": "GPL-3.0-only", - "version": "1.0.0" + "version": "1.0.1" } diff --git a/Common/agent-tooling/.codex-plugin/plugin.json b/Common/agent-tooling/.codex-plugin/plugin.json index 3632a686..974bf409 100644 --- a/Common/agent-tooling/.codex-plugin/plugin.json +++ b/Common/agent-tooling/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-tooling", - "version": "1.0.0", + "version": "1.0.1", "description": "Tools for authoring and verifying agent skills", "author": { "name": "Acumatica" diff --git a/Common/agent-tooling/.cursor-plugin/plugin.json b/Common/agent-tooling/.cursor-plugin/plugin.json index c590685c..e9b78563 100644 --- a/Common/agent-tooling/.cursor-plugin/plugin.json +++ b/Common/agent-tooling/.cursor-plugin/plugin.json @@ -5,5 +5,5 @@ "description": "Tools for authoring and verifying agent skills: friction-pattern extraction and skill quality verification", "keywords": ["distill", "skill-verification"], "license": "GPL-3.0-only", - "version": "1.0.0" + "version": "1.0.1" } diff --git a/Common/agent-tooling/README.md b/Common/agent-tooling/README.md index 3d8afb3a..761dfcf0 100644 --- a/Common/agent-tooling/README.md +++ b/Common/agent-tooling/README.md @@ -3,5 +3,5 @@ Plugin with tools for authoring and verifying agent skills: friction-pattern extraction and skill quality verification. ## Skills -- **[distill](skills/distill/)** — Extracts friction patterns from the current conversation into reusable skills +- **[distill](skills/distill/)** — Extracts recurring friction from completed work into reusable skills - **[verifying-skills](skills/verifying-skills/)** — Verifies a skill against best practices, skills docs, and a complete guide, producing a severity-bucketed review report diff --git a/Common/agent-tooling/skills/distill/SKILL.md b/Common/agent-tooling/skills/distill/SKILL.md index 13623f0e..4b804972 100644 --- a/Common/agent-tooling/skills/distill/SKILL.md +++ b/Common/agent-tooling/skills/distill/SKILL.md @@ -1,15 +1,15 @@ --- name: distill -description: Extract friction patterns from the current conversation into reusable skills +description: Extracts recurring friction from completed work into reusable skills. Use when a conversation exposed corrections, failed assumptions, or non-obvious guidance worth preserving for future tasks. metadata: - version: 1.0.0 + version: 1.0.1 --- -You are a friction extractor. You read the conversation that just happened, find where default AI behavior failed or would fail, and produce an executable skill that prevents that friction from recurring. If default behavior would handle it correctly, there is nothing to distill. +Act as a friction extractor. Read the conversation that just happened, find where default agent behavior failed or would fail, and produce an executable skill that prevents that friction from recurring. If default behavior would handle it correctly, there is nothing to distill. -The user invoking `/distill` is an implicit signal that this conversation contained friction worth preserving. Your job is to identify that friction, frame it as a reusable skill, and write it — with the user's approval. +Treat the user's request to distill the conversation as a signal that it contained friction worth preserving. Identify that friction, frame it as a reusable skill, and write it with the user's approval. -`$ARGUMENTS` — Optional focus guidance from the user. If provided, weight your analysis accordingly. +If the user supplies optional focus guidance, weight the analysis accordingly. --- @@ -27,9 +27,9 @@ If the user redirects you, continue. If they confirm there is nothing, stop. **Skill framing.** Can the friction be framed as a single coherent skill — a task-level behavioral specification with trigger conditions and prescriptions? If the patterns are project-contextual (codebase descriptions, project conventions) rather than task-level, say: -> "These patterns describe the project, not a reusable task behavior. They may belong in CLAUDE.md: [specific suggestions]. No skill to extract." +> "These patterns describe the project, not a reusable task behavior. They may belong in the project's persistent agent instructions: [specific suggestions]. No skill to extract." -Stop. `/distill` does not write to CLAUDE.md. +Stop. Do not write project-level instruction files as part of this workflow. **Elicitation.** In most cases, the conversation contains enough. Only if trigger conditions are genuinely ambiguous or multiple conflicting patterns exist, ask up to 2-3 short-answer questions. Expected frequency: under 10% of invocations. @@ -37,7 +37,9 @@ Stop. `/distill` does not write to CLAUDE.md. ## Phase 2: Propose -**Check existing skills.** Read `.claude/skills/distill-index.md` if it exists. Read any listed skills with overlapping trigger conditions. +**Resolve the skills root.** Use the user-specified destination when provided. Otherwise use the current project's existing canonical skills directory. If the project has no established skills directory and the destination cannot be inferred safely, ask where the reusable skill should live. + +**Check existing skills.** Read `[skills-root]/distill-index.md` if it exists. Read any listed skills with overlapping trigger conditions. **Mode detection:** - No overlap with existing skills -> **CREATE**. Say: "No existing skill covers this friction. I will create a new skill." @@ -55,14 +57,14 @@ Say: "Confirm to write, or tell me what to change. Say 'abort' to cancel." ## Phase 3: Write **For CREATE:** -1. Write skill to `.claude/skills/[skill-name].md` (kebab-case name derived from friction description) -2. Update or create `.claude/skills/distill-index.md` +1. Create `[skills-root]/[skill-name]/SKILL.md` (kebab-case name derived from the friction description). +2. Update or create `[skills-root]/distill-index.md`. 3. Say: "Skill written to [path]. Index updated." **For UPDATE:** -1. Copy existing skill to `.claude/skills/[skill-name].backup.md` (overwrites any previous backup) -2. Write modified skill -3. Update index (new last-updated date) +1. Copy the existing `SKILL.md` to `SKILL.backup.md` in the same skill directory (overwrites any previous backup). +2. Write the modified `SKILL.md`. +3. Update the index with the new last-updated date. 4. Say: "Original backed up to [backup-path]. Skill updated. Index updated." If the project uses git, note that the original is also recoverable from version control. @@ -76,7 +78,7 @@ Skills you create use this structure. Not every section is required — omit sec ``` --- name: [skill-name] -description: [One line: what friction this addresses] +description: [One line in third person: what friction this addresses and when the skill should be used] --- ## When to Use This Skill @@ -104,7 +106,7 @@ origin: [brief description of source conversation] **Quality standard.** Before writing, check your produced skill against these criteria: - Trigger conditions are observable from conversation context (not "when debugging" but "when the user reports a test failure and the error message references...") -- Every prescription is a delta from default AI behavior — if Claude would already do it, cut it +- Every prescription is a delta from default agent behavior — if a capable agent would already do it, cut it - Anti-patterns are specific enough that a future AI would recognize the situation (not "avoid assumptions" but "do not assume X when Y") **What BAD output looks like** (do not produce skills like these): @@ -116,14 +118,14 @@ origin: [brief description of source conversation] ## Index Format -The index at `.claude/skills/distill-index.md`: +The index at `[skills-root]/distill-index.md`: ``` # Distill Skill Index | Skill | Path | Created | Updated | Trigger Summary | |-------|------|---------|---------|-----------------| -| [name] | .claude/skills/[name].md | YYYY-MM-DD | YYYY-MM-DD | [1-line trigger] | +| [name] | [skills-root]/[name]/SKILL.md | YYYY-MM-DD | YYYY-MM-DD | [1-line trigger] | ``` If the index does not exist, create it on first invocation. If it references a skill file that no longer exists, note the discrepancy and remove the stale entry. If a distill-created skill file exists but is not in the index, add it. @@ -137,7 +139,7 @@ This is what a realistic produced skill looks like — use it as a quality refer ``` --- name: csv-column-mapping -description: Prevent silent column misalignment when parsing user-provided CSV files +description: Prevents silent column misalignment. Use when parsing user-provided CSV files whose requested columns have not yet been verified against the actual headers. --- ## When to Use This Skill @@ -164,7 +166,7 @@ origin: CSV parsing session where column name mismatch caused silent data corrup ## Hard Constraints -- **Never write to CLAUDE.md.** Suggest project-contextual patterns verbally if identified. Do not execute the write. +- **Never write project-level instruction files.** Suggest project-contextual patterns verbally if identified. Do not execute the write because this workflow is authorized only to create or update a reusable skill. - **Never silently modify an existing skill.** All modifications require preview and user confirmation. - **Always backup before update.** Copy the original file before writing changes. - **Never fabricate specificity.** If evidence is thin, say so. Lower your confidence — do not invent details. diff --git a/Common/agent-tooling/skills/verifying-skills/SKILL.md b/Common/agent-tooling/skills/verifying-skills/SKILL.md index a540e185..20c5f8b7 100644 --- a/Common/agent-tooling/skills/verifying-skills/SKILL.md +++ b/Common/agent-tooling/skills/verifying-skills/SKILL.md @@ -5,10 +5,8 @@ description: >- Skills Docs, Complete Guide, and Skill Creator — and produces a severity-bucketed review report with actionable findings. Use when asked to review a skill, verify a skill, audit a SKILL.md, check skill quality, or validate a skill against best practices. -disable-model-invocation: false -argument-hint: "" metadata: - version: 1.0.0 + version: 1.0.1 --- # Verifying Skills @@ -24,15 +22,13 @@ These abbreviation tags are used throughout the checklist and in the output repo | **[BP]** | [Skill Authoring Best Practices](https://code.claude.com/docs/en/best-practices) | | **[SD]** | [Claude Code Skills Docs](https://code.claude.com/docs/en/skills) | | **[CG]** | [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) (official Anthropic guide) | -| **[SC]** | Skill Creator (`/skill-creator`) — built-in Claude Code skill | +| **[SC]** | The current Skill Creator guidance available in the active host | ## Workflow -Before starting, create a task for each step below. Mark each task `in_progress` when you begin it and `completed` when done. - ### Step 1: Resolve the target skill path -The target skill directory path is provided as the argument (e.g., `/verifying-skills configs/.claude/skills/my-skill`). +Resolve the target supplied by the user to a skill directory (for example, `path/to/skills/my-skill`). If no argument is provided, ask the user for the path. @@ -56,58 +52,11 @@ Parse the YAML frontmatter to extract `name`, `description`, and all other field Read `references/checklist.md`. -Walk through each rule in the checklist. For every rule: - -1. **Check applicability.** Some rules only apply to specific skill types: - - Workflow rules (WF-01 through WF-05) only apply to skills with multi-step workflows, not minimal context-injection skills. - - DQ-06 (pushy description) is N/A for skills with `disable-model-invocation: true`. - - DQ-07 (negative triggers) only applies when sibling skills exist in similar domains. - - WF-02 (progress checklist) only applies to workflows with 5+ sequential steps. - - WF-03 (error handling) only applies to skills that invoke tools, MCP calls, or file operations. - - WF-04 (examples) only applies to skills with non-trivial workflows. - - WF-06 (fork has task) only applies to skills with `context: fork` in frontmatter. - -2. **Evaluate the rule.** For each applicable rule, determine pass or fail. - -3. **Record findings.** For each failure, capture: - - The specific location (file path and line number) - - A description of the problem and its consequence - - The source tag(s) from the checklist - - **Example finding:** - - **Location**: SKILL.md:12 - - **Problem**: Description uses first person ("I verify skills"), which causes discovery problems because the description is injected into the system prompt where point-of-view inconsistency confuses skill selection. - - **Reference**: **[BP]** "Always write in third person" +Walk through every rule in the checklist and use its applicability notes. For each applicable rule, determine pass or fail. For each failure, record the exact file and line, the problem and its consequence, and the checklist source tags. ### Step 4: Classify findings by severity -Apply severity using these criteria: - -**P1 — High Severity** (likely to cause functional problems at runtime): -- Wrong or non-existent tool names — Claude will try to call a tool that doesn't exist -- Missing required frontmatter fields — skill may not load -- SKILL.md missing or wrong case — skill won't be discovered -- Referenced files that don't exist — Claude will have no instructions for that code path -- Invalid frontmatter field names (`globs` instead of `paths`) — filter silently fails -- XML tags in description — security rejection risk -- Reserved name violations — blocked by platform - -**P2 — Medium Severity** (skill works but produces suboptimal results): -- Description in wrong voice or missing trigger phrases — hurts discovery -- Behavioral instructions in description instead of body — wrong progressive disclosure level -- ALWAYS/NEVER without reasoning — may cause brittle behavior -- Missing feedback loop in multi-step workflow — errors accumulate undetected -- Vague instructions — Claude must guess intent -- Exceeds size guidelines — excessive context consumption - -**P3 — Low Severity** (style and polish): -- Missing optional frontmatter fields (e.g., `argument-hint`) -- Awkward phrasing in triggers -- Redundant sections wasting tokens -- Reference files over 300 lines without TOC -- Missing examples or error-handling section for simple skills - -Use the checklist's default severity column as a starting point, but adjust based on context. For example, an unrecognized frontmatter field that is clearly a typo of a real field is P1, but a custom `metadata` sub-field is fine. +Use the checklist's default severity as a starting point and adjust only when the concrete consequence warrants it: P1 for likely runtime or discovery failure, P2 for materially reduced quality, and P3 for optional polish. ### Step 5: Generate the report @@ -115,6 +64,7 @@ Read `references/report-template.md`. Fill in the template: - Replace `{skill-name}` with the target skill's name - Write the context paragraph (what was reviewed, how many files, which sources) - Populate P1, P2, P3 sections with all findings in the prescribed format +- Put `P1 findings open: {count}` and `P2 findings open: {count}` immediately below their respective headings. Count only unresolved findings; clearly labeled closed findings may remain in the report without increasing the count. - Number findings sequentially across all severity levels - Build the summary table @@ -131,12 +81,3 @@ Print a short summary: - If any P1 findings: "**Fix P1 issues before deploying** — these are likely to cause functional problems." - If P2 but no P1: "No critical issues. Address P2 findings to improve quality." - If only P3 or clean: "Skill looks good. P3 items are optional polish." - -## Avoiding False Positives - -Not every rule applies to every skill. Be judicious: - -- **Minimal context-injection skills** (e.g., a 10-line skill that just loads domain context) should not be flagged for missing examples, error handling, feedback loops, or progress checklists. These rules target workflow skills. -- **User-invocable-only skills** (`disable-model-invocation: true`) have weaker discovery requirements — the description doesn't need aggressive trigger phrases since the user must explicitly invoke it. -- **Skills without conditional branches** cannot violate XR-03 (templates for all options) — this rule only applies when the skill offers discrete choices that map to different templates or reference files. -- **When genuinely uncertain** whether a rule applies, include the finding but note it as "potentially applicable — verify based on the skill's intended use case." Let the reviewer decide. diff --git a/Common/agent-tooling/skills/verifying-skills/references/checklist.md b/Common/agent-tooling/skills/verifying-skills/references/checklist.md index 9a08f05a..9f98c204 100644 --- a/Common/agent-tooling/skills/verifying-skills/references/checklist.md +++ b/Common/agent-tooling/skills/verifying-skills/references/checklist.md @@ -36,9 +36,9 @@ Default severity: **H** = likely P1, **M** = likely P2, **L** = likely P3. Final | FM-03 | `name` matches the skill's folder name. *Internal rule: sources say "should match"; we enforce strictly.* | [SD], [CG] | H | | FM-04 | `name` does not contain "claude" or "anthropic" (reserved) | [SD], [CG] | H | | FM-05 | `description` field is present | [CG] | H | -| FM-06 | `description` is under 1024 characters | [SD], [CG] | M | +| FM-06 | Apply the target runtime's limit: portable Agent Skills keep `description` at or below 1024 characters; Claude Code-only skills keep combined `description` and `when_to_use` text within the 1536-character listing budget | [SD], [CG], [SC] | M | | FM-07 | `description` contains no XML angle brackets (`<` or `>`) | [SD], [CG] | H | -| FM-08 | Custom fields should be placed inside `metadata`, not as top-level frontmatter keys (see section 8 for recognized fields). Escalate to H if the field name is a near-miss typo of a recognized field. *Internal rule: unrecognized top-level fields may be silently ignored, but we enforce discipline.* | [SD], [CG] | M | +| FM-08 | Top-level fields are valid for the skill's intended distribution target (see section 9). Canonical multi-platform skills use only portable Agent Skills fields; host-specific adapters may use that host's documented extensions. Escalate a near-miss typo of a supported field to H. | [SD], [CG], [SC] | M | | FM-09 | `name` field contains no XML angle brackets (`<` or `>`) | [BP] | H | | FM-10 | YAML frontmatter has `---` delimiters on both sides | [SD], [CG] | H | | FM-11 | `name` is at most 64 characters | [BP], [SD] | H | @@ -56,7 +56,7 @@ Default severity: **H** = likely P1, **M** = likely P2, **L** = likely P3. Final | DQ-05 | Trigger phrases sound natural ("Use when..." phrasing) | [BP] | L | All skills | | DQ-06 | "Pushy" enough for discoverability -- includes edge-case triggers | [SC] | M | Only model-invocable skills (N/A if `disable-model-invocation: true`) | | DQ-07 | Includes negative triggers if the skill could overlap with related skills | [CG] | L | Skills with sibling skills in similar domains | -| DQ-08 | Primary use case and key trigger phrases appear within the first 250 characters of the description — descriptions are truncated at this point in the skill listing | [SD] | M | All skills (N/A if `disable-model-invocation: true`) | +| DQ-08 | Primary use case and key trigger phrases appear early in the discovery text and fit within the target runtime's listing budget | [SD] | M | Model-invocable skills | ## 4. Instructions Quality @@ -135,11 +135,11 @@ Default severity: **H** = likely P1, **M** = likely P2, **L** = likely P3. Final ### Recognized Frontmatter Fields -From [SD] (Claude Code): `name`, `description`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `context`, `agent`, `argument-hint`, `model`, `effort`, `hooks`, `paths`, `shell`. +Portable Agent Skills fields: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`. -From [CG] (Agent Skills fields not listed in the [SD] table): `compatibility`, `license`, `metadata`. +Current Claude Code extensions: `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, `shell`. -Any field not in either list should be placed inside `metadata` or flagged (FM-08). +Use host extensions only when the skill is intentionally distributed to that host. For a canonical skill shared across runtimes, move host-specific behavior into the host adapter or omit it. Put custom data inside `metadata`; flag unsupported top-level fields under FM-08. ### Known Platform-Specific Tool Names diff --git a/Common/agent-tooling/skills/verifying-skills/references/report-template.md b/Common/agent-tooling/skills/verifying-skills/references/report-template.md index e0cc6636..f24cc673 100644 --- a/Common/agent-tooling/skills/verifying-skills/references/report-template.md +++ b/Common/agent-tooling/skills/verifying-skills/references/report-template.md @@ -28,7 +28,9 @@ Write the report to `Verification/{skill-name}-review.md` using this structure e ### P1 — High Severity (likely to cause functional problems) -{If no P1 findings: "No P1 findings."} +P1 findings open: {number of unresolved P1 findings} + +{List each open P1 finding below. If the count is 0, omit open finding entries. Closed findings may be summarized separately and must be clearly labeled as closed.} #### {n}. {Finding title} - **Location**: {file}:{line number or section name} @@ -37,9 +39,9 @@ Write the report to `Verification/{skill-name}-review.md` using this structure e ### P2 — Medium Severity (reduces quality or violates best practices) -{If no P2 findings: "No P2 findings."} +P2 findings open: {number of unresolved P2 findings} -{Same format as P1} +{List each open P2 finding using the same format as P1. If the count is 0, omit open finding entries. Closed findings may be summarized separately and must be clearly labeled as closed.} ### P3 — Low Severity (style/polish issues) @@ -59,6 +61,7 @@ Write the report to `Verification/{skill-name}-review.md` using this structure e ## Formatting Rules - Finding numbers are sequential across ALL severity levels (e.g., P1 findings 1-3, P2 findings 4-7, P3 findings 8-10) +- `P1 findings open` and `P2 findings open` count only unresolved findings and must be updated after corrections are verified - Every finding must reference at least one source with its abbreviation tag - Location should be as specific as possible -- prefer `SKILL.md:47` over just `SKILL.md` - Problem descriptions must explain the **consequence** (e.g., "Claude will try to call a non-existent tool"), not just restate the rule diff --git a/DEV/.claude-plugin/plugin.json b/DEV/.claude-plugin/plugin.json index 57b0de13..58ffdaa6 100644 --- a/DEV/.claude-plugin/plugin.json +++ b/DEV/.claude-plugin/plugin.json @@ -4,5 +4,5 @@ "description": "Skills and artifacts for Acumatica ERP Developers", "author": { "name": "Acumatica" }, "license": "GPL-3.0-only", - "version": "1.0.1" + "version": "1.0.2" } diff --git a/DEV/.codex-plugin/plugin.json b/DEV/.codex-plugin/plugin.json index cc4d6443..314ddc19 100644 --- a/DEV/.codex-plugin/plugin.json +++ b/DEV/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dev-toolkit", - "version": "1.0.1", + "version": "1.0.2", "description": "Skills and artifacts for Acumatica ERP developers", "author": { "name": "Acumatica" diff --git a/DEV/.cursor-plugin/plugin.json b/DEV/.cursor-plugin/plugin.json index 4aa3a6bd..868ba787 100644 --- a/DEV/.cursor-plugin/plugin.json +++ b/DEV/.cursor-plugin/plugin.json @@ -5,5 +5,5 @@ "description": "Skills and artifacts for Acumatica ERP Developers", "keywords": ["csharp", "dac", "customization", "upgrade", "publishing", "integration", "rest", "oauth", "modern-ui", "aurelia", "typescript", "custom-controls"], "license": "GPL-3.0-only", - "version": "1.0.1" + "version": "1.0.2" } diff --git a/DEV/skills/acumatica-modern-ui-control-builder/SKILL.md b/DEV/skills/acumatica-modern-ui-control-builder/SKILL.md index 8c2ce24c..a83c85d9 100644 --- a/DEV/skills/acumatica-modern-ui-control-builder/SKILL.md +++ b/DEV/skills/acumatica-modern-ui-control-builder/SKILL.md @@ -2,7 +2,7 @@ name: acumatica-modern-ui-control-builder description: Design, implement, review, and troubleshoot custom frontend controls for the Acumatica ERP Modern UI using Aurelia, TypeScript, HTML, SCSS, screen extensions, and appropriate backend field patterns. Use when building reusable Modern UI controls, binding DAC or graph-specific values, extending existing Acumatica screens, or diagnosing custom-control behavior and styling. metadata: - version: 1.0.0 + version: 1.0.1 --- # Acumatica Modern UI Control Builder @@ -192,7 +192,7 @@ Before finalizing an implementation, check: - User-facing strings are localizable; technical tokens are not localized. - The control is added through an HTML extension for existing screens. - For existing Acumatica screens, TypeScript and HTML extensions are used instead of editing the base screen definition files. -- Both HTML and TypeScript extension files should follow the following naming convention: __. For example, RS301000_PhoneRepairShop_RecordInsightsPanel.ts or RS301000_PhoneRepairShop_RecordInsights.html. Explicitly mention that the customization project name is assumed. +- Both HTML and TypeScript extension files should follow the following naming convention: __. For example, RS301000_PhoneRepairShop_RecordInsightsPanel.ts or RS301000_PhoneRepairShop_RecordInsightsPanel.html. Explicitly mention that the customization project name is assumed. - Both TypeScript and HTML extension files should be added to the corresponding extensions folder of the screen. The standard folder and file structure is `FrontendSources/screen/src/development/screens///extensions`. For example, `FrontendSources/screen/src/development/screens/RS/RS301000/extensions`. - Testing covers default, warning/error, empty/null, and state-transition cases. diff --git a/Verification/acumatica-modern-ui-control-builder-review.md b/Verification/acumatica-modern-ui-control-builder-review.md index 546aaf32..1cad6438 100644 --- a/Verification/acumatica-modern-ui-control-builder-review.md +++ b/Verification/acumatica-modern-ui-control-builder-review.md @@ -2,7 +2,7 @@ ## Context -Reviewed `DEV/skills/acumatica-modern-ui-control-builder` on 2026-08-26. Scope included `SKILL.md`, `agents/openai.yaml`, and `references/patterns.md`. Verification covered folder and frontmatter validity, discovery metadata, instruction quality, workflow completeness, progressive disclosure, cross-reference integrity, platform-neutral paths, and Codex UI metadata. The previously reported navigation issue was resolved by adding a linked table of contents to the code-pattern reference. Obsolete icon metadata and its bundled SVG were removed. +Reviewed the corrected `DEV/skills/acumatica-modern-ui-control-builder` package on 2026-09-04, including `SKILL.md`, `agents/openai.yaml`, `references/patterns.md`, and the GitHub Copilot discovery adapter. Verification covered folder and frontmatter validity, discovery metadata, workflow completeness, progressive disclosure, cross-reference integrity, code-template routing, naming consistency, and adapter linkage against Skill Authoring Best Practices, Skills Docs, the Complete Guide, and Skill Creator guidance. The TypeScript and HTML extension filename examples now use the same custom-control name. The canonical quick validator and repository-wide validator both passed. ## Verification Sources @@ -19,11 +19,11 @@ Reviewed `DEV/skills/acumatica-modern-ui-control-builder` on 2026-08-26. Scope i ### P1 — High Severity (likely to cause functional problems) -No P1 findings. +P1 findings open: 0 ### P2 — Medium Severity (reduces quality or violates best practices) -No P2 findings. +P2 findings open: 0 ### P3 — Low Severity (style/polish issues) @@ -33,4 +33,6 @@ No P3 findings. ## Summary Table -No findings. +| # | Severity | Finding | Source | +|---|---|---|---| +| — | — | No remaining findings after corrections | — | diff --git a/Verification/distill-review.md b/Verification/distill-review.md new file mode 100644 index 00000000..98a0514e --- /dev/null +++ b/Verification/distill-review.md @@ -0,0 +1,38 @@ +# Review: `distill` Skill + +## Context + +Reviewed the corrected `Common/agent-tooling/skills/distill` package on 2026-09-04, including the canonical `SKILL.md` and its synchronized GitHub Copilot discovery adapter. The review checked folder and frontmatter validity, discovery metadata, workflow safety, generated-skill structure, platform neutrality, and adapter linkage against Skill Authoring Best Practices, Skills Docs, the Complete Guide, and Skill Creator guidance. The workflow creates directory-based skills with `SKILL.md`, resolves a host-neutral skills root, avoids host-specific runtime conventions, and includes trigger context in discovery descriptions. The canonical quick validator passed. + +## Verification Sources + +| Abbreviation | Source | +|---|---| +| **[BP]** | [Skill Authoring Best Practices](https://code.claude.com/docs/en/best-practices) | +| **[SD]** | [Claude Code Skills Docs](https://code.claude.com/docs/en/skills) | +| **[CG]** | [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) (official Anthropic guide) | +| **[SC]** | Skill Creator skill instructions | + +--- + +## Findings + +### P1 — High Severity (likely to cause functional problems) + +P1 findings open: 0 + +### P2 — Medium Severity (reduces quality or violates best practices) + +P2 findings open: 0 + +### P3 — Low Severity (style/polish issues) + +No P3 findings. + +--- + +## Summary Table + +| # | Severity | Finding | Source | +|---|---|---|---| +| — | — | No remaining findings after corrections | — | diff --git a/Verification/verifying-skills-review.md b/Verification/verifying-skills-review.md new file mode 100644 index 00000000..dfc26ec8 --- /dev/null +++ b/Verification/verifying-skills-review.md @@ -0,0 +1,38 @@ +# Review: `verifying-skills` Skill + +## Context + +Reviewed the corrected `Common/agent-tooling/skills/verifying-skills` package on 2026-09-04, including `SKILL.md`, both referenced Markdown files, and its synchronized GitHub Copilot discovery adapter. The review checked frontmatter portability, source currency, workflow completeness, progressive disclosure, cross-reference integrity, and adapter linkage against Skill Authoring Best Practices, current Skills Docs, the Complete Guide, and Skill Creator guidance. The canonical skill uses portable frontmatter, the checklist distinguishes portable fields from current host extensions and their respective listing limits, and detailed policy is kept in the checklist. The canonical quick validator and repository validator passed. + +## Verification Sources + +| Abbreviation | Source | +|---|---| +| **[BP]** | [Skill Authoring Best Practices](https://code.claude.com/docs/en/best-practices) | +| **[SD]** | [Claude Code Skills Docs](https://code.claude.com/docs/en/skills) | +| **[CG]** | [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) (official Anthropic guide) | +| **[SC]** | Skill Creator skill instructions | + +--- + +## Findings + +### P1 — High Severity (likely to cause functional problems) + +P1 findings open: 0 + +### P2 — Medium Severity (reduces quality or violates best practices) + +P2 findings open: 0 + +### P3 — Low Severity (style/polish issues) + +No P3 findings. + +--- + +## Summary Table + +| # | Severity | Finding | Source | +|---|---|---|---| +| — | — | No remaining findings after corrections | — |