## 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>
Records the upstream agentskills.io sources that informed skill-author,
completing the research → docs → skill provenance chain introduced in
the previous commit.
- New references/sources.md with all 7 extracted agentskillsio sources,
Contributing files attributed per-source to SKILL.md, references/deployment-modes.md,
and references/scripts.md
- source_keys frontmatter added to SKILL.md (all 7 slugs), references/deployment-modes.md
(agentskills-spec), and references/scripts.md (agentskills-using-scripts)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds a sources provenance step to the skill creation workflow so the
chain from research output to skill content is traceable. Closes#4.
- New scaffold template `assets/templates/references/sources.md` mirroring
the research skill's sources.md format (slug → URL, description,
contributing files, status)
- `source_keys` commented-out optional field added to the SKILL.md
template, mirroring how research topic files link back to sources
- New Step 5 in the creation workflow: populate references/sources.md
from research input (attributing contributing skill files) or delete it
if no research was provided; add source_keys to SKILL.md and any
references/*.md files
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Skills and evals migrated from .agents/ to plugins/bin/ plugin directory.
Remove .mcp.json, provider-manifest.sh, and skills-lock.json legacy artifacts.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Status now calls list_issues + list_pull_requests in parallel instead
of passing a non-existent type parameter to list_issues. Stale type
reference in Gotchas removed.
Issue create now infers labels from conversation context (Kind/*/
Priority/*/Status/*) before the write call, resolving names to IDs
via label_read first.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds the gitea skill to kyberforge — a dispatch skill for managing
Defame1297/holocron via Gitea MCP from within Claude Code. Covers
issues, PRs, milestones, labels, branches, and status. Owner/repo
derived from git remote at runtime; no config required.
Also adds research docs (api-reference, data-model, examples,
overview, troubleshooting) and token-access reference used during
authoring and available for runtime scope lookups.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Body discipline: collapsed 4-bullet script rules to single critical callout
(no interactive prompts); full contract stays in references/scripts.md.
stderr discipline: redirect all confirmation/progress output in new-skill.sh
to stderr per scripts.md contract. Also expands references/scripts.md with
input validation and --help guidance.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016z2ZFYHQCex8yZAMVMTZzZ
Closes#5. Single authoring skill replaces the factory trio — one set of
standards, one script, one place for future governance rules. Routes to
create or improve flow based on context. Passes skill-audit with no findings.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016z2ZFYHQCex8yZAMVMTZzZ
- Rewrite assets/templates/tests/README.md with correct repo-root context and
SKILL_NAME placeholder in bats run command (was: `bats tests/`, wrong CWD)
- Add sed substitution for tests/README.md in new-skill.sh so SKILL_NAME is
replaced in scaffolded test docs; test added to new-skill.bats (red→green)
- Remove /write-eval reference from skill-improve SKILL.md; reword as direct
action since the skill does not exist in the kyberforge plugin
- Remove self-referential README.md rows from skill-audit and skill-improve
Files tables to match template and skill-write convention
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- validate.sh: move FAIL lines and failure summary to stdout; stderr
reserved for fatal script errors only (missing SKILL.md, bad args)
- skill-audit SKILL.md: replace concrete plugins/kyberforge/skills/...
example with abstract placeholder to fix meta-circularity
- skill-write SKILL.md: rephrase placeholder section-heading instruction
to remove embedded FILL IN: from a code span, clearing validator false positive
- skill-improve SKILL.md: wrap Step 2 root-cause example in a text fence
- skill-write assets/templates/README.md: update Files table to individual-
file rows so skill-audit can verify per-file coverage
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- skill-audit: remove contradictory skip clause in Step 2 (binary only)
- skill-improve: drop redundant "Fix the root" heading; keep specific directive
- skill-write: add section-rename guidance to body discipline step
- template SKILL.md: make Instructions heading an explicit FILL IN placeholder
- template README.md: remove "Invoke via your agent tool:" prefix to match convention
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- skill-audit: promote internal-working gotcha to ## Gotchas section;
narrow cross-plugin path check to exclude tests/ (dev-only, repo-level
deps are expected); require tests/README.md to declare that dependency
- skill-write/skill-improve: reorder descriptions to lead with "Use when..."
for consistency with skill-audit and the agentskills.io spec trigger pattern
- skill-write: add tests/README.md with self-contained bats setup instructions;
remove cross-skill reference to skill-audit's tests/README.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Both validate.bats and new-skill.bats constructed SCRIPT using
$(dirname "$BATS_TEST_FILENAME"), which resolves to tests/ — causing
every test to fail with file-not-found. Fixed to use
$BATS_TEST_DIRNAME/../scripts/ to reach the actual scripts/ directory.
Also clarifies that bats-support/bats-assert must be installed from the
repo root (not the skill root) to match where the tests load them from,
and adds text language tags to three output-template code blocks in
skill-audit's SKILL.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Move test infrastructure (validate.bats, new-skill.bats) from scripts/ to
tests/ — the spec defines scripts/ as executable code agents can run, so
test files don't belong there. Add tests/README.md placeholders with
bats-support dependency declaration.
Update skill-audit to permit tests/ and flag other unlisted directories,
add scripts/ purpose check, and add /skill-improve near-miss exclusion.
Update skill-improve and skill-write to cover tests/ in directory lists,
scaffold template, and authoring guidance.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace verbose three-pass output (punch list + priority table + fix
proposals) with a compact findings-only report: coverage line, findings
grouped by dimension with Why+Fix per entry, and a result block with
/skill-improve handoff. Suppress PASS lines — absence confirms pass.
Fix validate.bats executable bit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Deletes the neuledge-context skill (.agents/skills/) and four kyberforge
plugin skills — marketplace-architect, plugin-create, promptfoo, and
write-agent — along with associated docs (adding-agents.md,
plugin-marketplace-architecture.md).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Applies evidence-based improvements to existing skills using signals
from grill sessions, audit reports, eval failures, and inline feedback.
Groups signals by root cause before editing to avoid per-symptom patching.
Hands off to /skill-audit on completion.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Two data errors in sources.md files:
- agentskillsio/sources.md: Contributing files used agentskills-* prefix
(e.g. agentskills-overview.md) but actual filenames have no prefix
(overview.md, specification.md, etc.)
- write-agent/references/sources.md: plugin-marketplace-architecture entry
used a machine-specific absolute path; replaced with repo-relative path
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Separates development-time reference material from live plugin docs.
agentskillsio/, agentsmd/, and examples/skill-write/ are not shipped with
the plugin — grouping them under research/ makes that boundary explicit.
README now lists all top-level files and explains what research/ is for.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Bats files moved up to scripts/ directly; tests/ subdirectory was non-spec
and created a directory structure not defined by agentskills.io.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Reorder skill-audit description to lead with 'Use when...' trigger (P3)
- Add concrete example to 'control calibration' body discipline check (P4)
- Add bats test files to README file tables for both skills
- Fix REPO_ROOT and SCRIPT paths in bats files after tests/ subdirectory removed
- Add three lessons: plugin cache isolation, spec-grounded rubrics, test file placement
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
