## Why
Two issues were found in `validate-provenance.sh` by `/skill-audit`:
1. `find_plugin_root` only walked up looking for bare `plugin.json`, missing
the `.claude-plugin/plugin.json` layout used by kyberforge plugins — matching
the logic already present in `validate.sh`.
2. Check numbers in `--help` and inline comments had a gap (0,1,2,4,5,6) from
a previously removed check, making the numbering confusing to readers.
## Implementation Notes
Check numbers renumbered sequentially 0–5 in both the `--help` output block
and the inline `# --- Check N:` comments. The `find_plugin_root` condition now
mirrors the `detect_scope` function in `validate.sh`.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
Corrects three FAIL findings from the skill-audit run:
- Scope detection table in SKILL.md and references/scripts.md now lists all
four plugin-marker variants the script actually checks (plugin.json,
.claude-plugin/plugin.json, .plugin/plugin.json, .github/plugin/plugin.json)
- assets/README.md copilot.agent.md description was wrong about field set;
replaced with accurate CLI-format description noting excluded cloud/IDE fields
and the Copilot tool aliases actually used.
Also applies the SUGGESTION: moves the conditional reference
(`If the destination is a plugin directory, read references/deployment-modes.md`)
out of the ## Gotchas section body and into ## Route as a standalone line,
immediately after ## Gotchas closes.
INFO findings (source_keys frontmatter) were already present in both
references/README.md and references/scripts.md — no change needed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
The description sentence "Handles both the full create flow (scaffold → fill →
validate) and the improve flow (signals → root cause → edit → audit)." describes
internal mechanics rather than user intent. The surrounding trigger phrases already
cover both create and improve intents, so this sentence adds no triggering value
and violates the description principle of focusing on what the user is trying to
achieve.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
Remove phantom cross-file name-match claim from SKILL.md manual fallback
list (validate.sh has no such check). Fix broken bats stem-mismatch test
to overwrite the Copilot file instead of the CC file, exercising the
actual Copilot stem check.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
- Fix validate.sh: remove incorrect name==stem check for CC files (CC docs say filename need not match name field); keep check for Copilot CLI only
- Fix validate.sh: plugin scope detection now checks both plugin.json and .claude-plugin/plugin.json
- Fix validate.sh: Copilot cloud/IDE agents (.github/copilot/agents/) have name as optional; path-based guard added
- Add validate.sh checks: Copilot body length >30,000 chars (SUGGESTION), Copilot-only fields in CC files (FAIL), subagent-unavailable tools in tools field (SUGGESTION)
- Add references/description-quality.md as conditional escape hatch for borderline description findings
- SKILL.md: name five audit dimensions in description; sharpen indirect-trigger phrasing
- SKILL.md: label pair-mandate as kyberforge project convention, not platform requirement
- SKILL.md: scope redundant name-match/body-empty checks to manual fallback only
- SKILL.md: add conditional reference to description-quality.md; update provider-safety description for new check categories; fix plugin scope gotcha to mention .claude-plugin/plugin.json
- SKILL.md: add INFO tier to result block template
- Add source_keys frontmatter to references/README.md; update sources.md to add description-quality.md to contributing files
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
- references/sources.md: add YAML frontmatter with source_keys to fix provenance chain break
- SKILL.md description: make create/improve duality explicit ("Handles both the full create flow ... and the improve flow ...")
- SKILL.md Step 2: add inline metadata.source_keys instruction — fill early, not deferred to Step 5
- SKILL.md Step 6 (create) / Step 5 (improve): add pre-audit manual checklists and version bump conventions (minor for create, patch for improve)
- README.md: correct false claim that the skill bumps plugin manifests; it bumps metadata.version only
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
agent-author produces agents/sources.md at plugin scope to record which
research sources informed which agent files. agent-audit had no way to
validate this chain, leaving stale or missing provenance undetected.
## Implementation Notes
Validation is per-pair (the given agent file + its counterpart) rather
than plugin-wide, keeping the scope consistent with validate.sh. The
script exits 0 silently for non-plugin-scope agents.
source_keys is top-level in both CC .md and Copilot .agent.md files
(not under metadata:) to avoid conflict with Copilot's own metadata
field semantics. Checks 0, 1, 2, 4, 5, 6 mirror the skill provenance
set; upstream research-doc cross-reference checks (7, 8) are deferred.
agent-author Steps 2, 3, and 4 updated to formally specify the
agents/sources.md format and instruct authors to add source_keys to
both files when research sources are in context.
Refs: #60
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
The last acceptance criterion from #11: agent-author's close step should
reference agent-audit so authors are prompted to validate the pair before
shipping, matching the pattern skill-author uses with skill-audit.
Refs: #11
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
agent-author produces paired agent definition files (Claude Code .md +
Copilot .agent.md) but had no companion audit skill to validate them.
agent-audit fills that gap, giving the same structured PASS/FAIL report
that skill-audit provides for SKILL.md files.
## Implementation Notes
- validate.sh uses scope detection (walk up for plugin.json / .git) to
locate the counterpart file and determine whether plugin-silently-ignored
fields (hooks, mcpServers, permissionMode) should be flagged
- CC-only and silently-ignored field lists are read from
references/field-inventory.md at runtime rather than hardcoded —
provenance back to the research corpus; see ADR-0019
- Single-file invocation (pass either file, counterpart derived) chosen
over directory or name+root — see ADR-0018
- 12 bats tests cover provider detection, scope detection, all FAIL paths,
and clean-pair pass
## Impact
- kyberforge bumped to v1.1.2
- agent-author close step should be updated to reference agent-audit (#11)
- Provenance/sources chain check deferred to #60
ADR: docs/adr/0018-agent-audit-single-file-invocation.md
ADR: docs/adr/0019-agent-audit-field-inventory-reference.md
Refs: #11
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
The existing kyberforge research covered skills vs agents (ADR-0010),
Copilot track selection, and agent scope hierarchy — but had no documented
basis for three practical decisions: when to use MCP servers vs skills vs
agents, when hooks are the right tool vs skills, and when bin/ is
appropriate vs scripts/ inside a skill directory. Without this, the
plugin-author and agent-author skills have no research backing for those
choices.
## Implementation Notes
Sourced from official Claude Code plugin docs (code.claude.com), official
GitHub Copilot CLI docs (docs.github.com), and the Copilot
customization-cheat-sheet and comparing-cli-features pages — the latter
containing the only official "putting it together" decision table across
components. Context7 MCP was the primary retrieval mechanism; web reads
deepened the hooks and bin/ content.
Three files produced:
- overview.md — mental model, component roles, cross-provider portability
- decision-guide.md — explicit decision tables for all three gaps,
including anti-patterns and Copilot surface support matrix
- hooks.md — full lifecycle event reference, stdin/stdout schema,
hookSpecificOutput per event, plugin scope restriction
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
Without this guard, the agent could bypass the skill and call Gitea MCP
tools directly, skipping owner/repo resolution and label-ID normalization.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
The UPDATE flow only bumped version when the version field itself was the
target. Metadata changes (description, keywords, author) went out without a
version bump, making them invisible to consumers with a cached copy.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Same gap as skill-author: no instruction to bump the plugin version after
creating or modifying an agent inside a plugin.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
README "What it does" didn't reflect the plugin version bump step added
to both create and improve flows.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
The skill had no instruction to bump the catalog version after ADD, REMOVE, or UPDATE operations. Clients cache the marketplace catalog and use the version field to detect changes — without a bump, the new state is invisible until a forced refresh.
## Implementation Notes
Added a Gotcha explaining the rule and semver convention (ADD/REMOVE → minor, UPDATE → patch). Added a dedicated "Bump catalog version" step to each mutating flow. Updated README to match.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
check-manifests.sh requires all paths declared in plugin.json to exist.
Adds empty hook and MCP server stubs matching kyberforge convention.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
The Obsidian MCP server config was living at the repo root, making it
a repo-level concern rather than part of the plugin it belongs to.
Moving it into plugins/bin/ means the plugin is self-contained and the
server travels with it on install.
## Implementation Notes
mcpServers is declared in the Copilot manifest (plugin.json) because
Copilot requires explicit path declarations. CC auto-discovers .mcp.json
from the plugin root so no change to the CC manifest is needed.
Bumps version to 1.0.3 in both manifests.
---
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Both skills exist on disk but were missing from the plugin README and the
skills/ directory README. Adding them so the listings stay consistent with
the actual skill set.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Several small quality issues accumulated across plugin-author and
marketplace-author: the plugin-author description was ambiguous about
scope, the ADD flow asked an unnecessary clarifying question when local
path is the obvious default, VALIDATE had redundant wording already
captured inline, the keywords field was missing from the validation
checklist, and tests/README.md was a placeholder with nothing to test.
## Implementation Notes
- plugin-author: tightened description scope to "inside those
directories"; added `keywords` identical-in-both-manifests check to
VALIDATE checklist.
- marketplace-author: moved reserved-prefix constraint from gotchas
into the ADD checklist item; replaced the four-option prompt with a
default+escape-hatch ("I'll treat this as local path — is that right?");
folded the validate-from-root note inline and removed trailing padding;
deleted tests/README.md — no scripts/ directory exists, so the
placeholder was noise.
- README.md: removed the tests/README.md row from the file table.
## Why
Version sync across all plugin manifest locations so the CC plugin loader,
the .github marketplace mirror, and the canonical plugin.json files all
report the same version.
## Impact
Consumers fetching the plugin via the marketplace will see the updated
version entry.
## Why
The manifest-fields tables in both skills used imprecise labels ("CC-only",
"Copilot-only") that conflated two distinct reasons a field appears in only
one manifest: platform constraint (the other tool does not support the field
at all) versus repo convention (both tools support it, but the scaffold places
it in one manifest by design). This caused agents to treat convention
boundaries as hard platform constraints, producing unnecessary errors when
updating manifests for dual-tool repos.
Provenance was also incomplete: sources.md files were missing entries for
sources that had been consulted and were already contributing to SKILL.md
and manifest-fields.md content, making the evidence chain unverifiable.
## Implementation Notes
Field classification now uses three explicit categories — shared, platform
(one tool does not support the field), and convention (both tools support it;
scaffold places it in one manifest by design). The distinction matters because
convention fields may legitimately appear in the other manifest when there is
a deliberate reason; platform fields may not.
New gotchas added to plugin-author: agent files silently ignore hooks,
mcpServers, and permissionMode frontmatter; claude plugin tag --push requires
a clean working tree; --dry-run preview before tagging; --strict flag on
validate. New gotchas in marketplace-author: metadata object as Copilot CLI
canonical location for top-level fields; strict: false for dual-tool plugins;
sha takes precedence over ref for pinning; --strict flag on validate.
tests/ removed from plugin-author because new-plugin.sh has no branching
logic warranting a bats suite at this stage.
## Impact
Skill prompt changes only — no runtime code affected. Agents using these
skills will now correctly distinguish convention from constraint when deciding
which manifest to update for a given field.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Plugin and marketplace management had no governed authoring path. Creating or
updating a plugin required knowing the dual-manifest convention, version parity
rules, and directory skeleton by memory — nothing enforced consistency or guided
the process.
`/plugin-author` closes that gap by owning the full plugin scaffold lifecycle:
create, update, rename, and release. `/marketplace-author` handles the
marketplace-facing side: register, deregister, and update plugin entries in
`marketplace.json`.
ADR-0016 codifies the version parity convention (identical `version` in both
`plugin.json` and `.claude-plugin/plugin.json`) that `/plugin-author` now
enforces. The two plugin.json files in this repo are backfilled to comply
(keys also sorted to pass the pretty-format-json hook). CONTEXT.md gains
glossary entries for "plugin scaffold" and "version parity" so future agents
have shared vocabulary for these concepts.
## Implementation Notes
`/plugin-author` ships a `scripts/new-plugin.sh` scaffold script that generates
the directory skeleton and both manifests in one shot; the skill calls the script
rather than generating files ad hoc so the scaffold is reviewable and repeatable.
Version parity is an invariant, not a suggestion — the skill will fail loudly
on create/update if the two versions would diverge.
ADR: docs/adr/0016-plugin-version-parity.md
## Why
Plugin cache is keyed by version string. Adding pc-author and pc-run
skills requires a version bump so claude plugin update resolves a new
cache directory and picks up the new skills.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P87CiC58Ru2PPWYTeXtjHT
## Why
Pre-commit config management was entirely manual — no skill existed to
help create, modify, or validate `.pre-commit-config.yaml`, or to run,
install, and maintain the pre-commit setup. These two skills close that
gap with clear scope separation: authoring vs. execution.
## Implementation Notes
- `pc-author` owns `.pre-commit-config.yaml` only (no hook publishing,
no install). Runs `pre-commit validate-config` after every write.
Shallow file-extension scan drives proactive hook recommendations;
rev staleness is flagged against `references/hooks-by-language.md`
rather than hardcoded versions. Remove path reverts on failure.
- `pc-run` owns install, run, autoupdate, gc, and clean. Defaults to
`--all-files`. Install warns about existing `.git/hooks/` files being
overwritten by `-f`. Clean requires HITL confirmation. Failure
interpretation delegates to `references/failure-patterns.md`.
- Provenance wired to `plugins/kyberforge/docs/research/docs/pre-commit/`.
- Both skills resolve via the existing `"skills/"` glob in `plugin.json`.
## Impact
Two new slash commands available after `claude plugin install kyberforge@holocron`:
`/pc-author` and `/pc-run`.
Refs: #12
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P87CiC58Ru2PPWYTeXtjHT
## Why
The initial research pass focused on agent definitions. An audit identified
critical and minor gaps in both doc sets around plugin publishing, marketplace
registration, and the Copilot extensibility model.
## Implementation Notes
Claude Code gaps filled: end-to-end publish walkthrough (scaffold → validate →
tag → host → register), CLI vs in-session command surface equivalence, all six
marketplace source URL formats, plugin update/upgrade lifecycle, interactive
plugin manager UI, private marketplace auth, `commands` vs `skills/` distinction.
Copilot gaps filled: discovered that the GitHub App-based Copilot Extensions
track was sunset November 2025. Created copilot-extensions.md as historical
reference (deprecated, with MCP servers as the current replacement path).
Documented the agent vs. skillset extension type distinction, OAuth install
flow, and VS Code Chat Participants as the surviving @mention mechanism.
overview.md updated with a "Which Track to Use" decision table covering all
four active tracks plus the deprecated one.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
skill-author explicitly excludes agent definition files ("Do not use to author
agent definition files"). No factory skill existed to create or improve the
.md / .agent.md files that define Claude Code subagents and Copilot CLI agents
in a plugin, project, or user scope. This fills that gap.
## Implementation Notes
Single-root scaffold convention: new-agent.sh <name> <root> derives both
provider file paths from the root by convention — plugin scope (plugin.json
present) writes both files into <root>/agents/; non-plugin scope writes
.claude/agents/<name>.md and .github/agents/<name>.agent.md. This keeps
input minimal while always generating both provider files. See ADR-0015.
Routing is file-level (not directory-level like skill-author): neither file
exists → create flow; at least one exists → improve flow; scaffold is a
file-by-file no-op so retries are safe.
No companion agent-audit skill — inline validation in the close step covers
the simpler agent field contract. agent-audit is tracked as a follow-on.
## Impact
Closes the skill-author gap for agent definitions. Follow-ons tracked in
Gitea #11: agent-audit skill and --copilot-dest override flag for non-standard
Copilot project paths.
---
ADR: docs/adr/0015-agent-author-dual-provider-scaffold.md
Refs: #10
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Parallel research track to the Claude Code plugins research already
committed. Needed to understand GitHub Copilot's extensibility model
before designing cross-tool plugin compatibility for the kyberforge
plugin system.
## Implementation Notes
Three distinct Copilot extension tracks are covered: CLI plugins
(plugin.json + marketplaces), cloud/IDE custom agents (frontmatter .md
files committed to repos), and the SDK programmatic API. The SDK track
got its own topic file (sdk.md) because the content doesn't fit neatly
into the default topic list. Sources include Context7 (/websites/github_en_copilot),
both user-provided reference URLs, and four additional deepened pages.
## Impact
Provides a reference baseline for evaluating .claude-plugin/ / plugin.json
compatibility between Claude Code and Copilot CLI — the two formats share
a manifest discovery path and the strict:false field enables cross-tool
plugin distribution.
---
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Research from official docs (code.claude.com) and Context7, covering
plugin manifest schema, agent definition frontmatter spec, scope
priority, marketplace distribution, and plugin subagent restrictions.
Foundation for writing an agent-author skill.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
skill-audit description understated its coverage by omitting three audit
dimensions (patterns, scripts, provenance); README carried the same stale
list. skill-author had an unconditional reference trigger that should be
conditional on whether a script is being added.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove implementation-focused sentence from description (was not user-intent
language per agentskills.io spec)
- Move source_keys template comment under metadata: block to match Step 5's
instruction; contradicted agents scaffolding before reading Step 5
- Add Step 6 to new-skill.sh next-steps (populate references/sources.md);
renumber validate step to 7 — script was missing the sources step entirely
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
references/sources.md Research doc: fields are development-only provenance
pointers, not runtime references — they intentionally target paths outside the
skill directory and are expected to be non-resolvable after plugin install.
validate-provenance.sh degrades gracefully when they don't resolve.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add Research doc: pointer to all 7 agentskillsio entries so the new
validate-provenance.sh upstream checks resolve correctly for this skill.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Step 5 now records a Research doc: path per entry in references/sources.md,
pointing to the upstream plugin-level research file the slug was drawn from.
Updates the sources.md template to include the new required field, formalise
comma-separated Contributing files, and document the (none) convention.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add Research doc: pointer to all 7 agentskillsio entries so the new
validate-provenance.sh upstream checks can resolve the research source.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add validate-provenance.sh and validate-provenance.bats to enforce the
sources provenance chain introduced by skill-author. Eight checks cover
slug cross-references, Contributing files existence, bidirectional
source_keys linkage, Research doc: field presence, and upstream research
doc alignment (forward INFO, reverse FAIL). Adds a new Provenance report
dimension and INFO finding level (observational, exit-0, counted
separately as · P info in the result block).
Closes#8
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Records the upstream agentskills.io sources that informed skill-audit,
continuing the research → docs → skill provenance chain.
- New references/sources.md with 7 extracted sources attributed to skill files;
agentskills-llms-txt demoted to discovery-only comment per skill-author precedent
- source_keys frontmatter added to SKILL.md (5 slugs), references/body-discipline.md
(agentskills-spec, agentskills-best-practices), and references/description-quality.md
(agentskills-spec, agentskills-optimizing-descriptions)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- script: new-skill.sh now exits 0 when target already exists (idempotent
retry-safe) instead of exit 1; --help updated to reflect narrowed error cases
- test: updated bats test to assert success and "nothing to do" output
- body: removed speculative "Extract the skill from a real task" advice
(human-targeted, not agent-actionable)
- formatting: converted H4 headings in Step 2 to bold text (H2/H3 two-tier model)
- provenance: removed orphan agentskills-llms-txt entry from references/sources.md;
added discovery-only comment
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
