Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

bug: skill-author loses source provenance — research output not recorded in skill references #4

New Issue
Closed
opened 2026-06-23 17:03:40 +00:00 by Claude · 0 comments
Claude commented 2026-06-23 17:03:40 +00:00
Collaborator
Copy Link

Summary

/skill-write accepts research docs as prerequisites but never records them as sources. Skills built from /research output have no provenance chain from upstream docs → research files → skill is silently broken.

Steps to reproduce

  1. Run /research agentskills.io plugins/kyberforge/docs/research/docs/agentskillsio/ — produces topic files + sources.md
  2. Run /skill-write with those research docs as input
  3. Inspect the output — no provenance present

Root cause

Missing skill-write step — skill-write has no step/template instructing the agent to read the research sources.md and create sources.md files for the skill.

Solution

Agreed approach from grill session (2026-06-26):

Convention: references/sources.md + source_keys frontmatter

The provenance chain mirrors the research skill's output format:

  • /research writes sources.md to plugin-level docs (e.g. plugins/<plugin>/docs/research/docs/<topic>/)
  • /skill-author reads those docs and records provenance in the new skill

Changes to skill-author:

  1. assets/templates/references/sources.md — new scaffold template mirroring the research sources.md format exactly (slug → URL, Description, Contributing files, Status). One placeholder entry with FILL IN: values. Comment instructs: fill in after writing skill files, or delete if no research was provided.

  2. assets/templates/SKILL.md — add source_keys as a commented-out optional field under metadata, same treatment as license and compatibility.

  3. SKILL.md (skill-author itself) — new Step 5 in the "Creating a new skill" flow:

    • If research sources.md is in conversation context: filter to extracted entries, populate references/sources.md with Contributing files pointing to skill files (not research topic files); add source_keys to SKILL.md metadata and to each references/*.md file
    • If no research sources in context: delete references/sources.md
    • Current Step 5 (validate) becomes Step 6

Key design decisions:

  • Trigger: only when research sources.md is present in conversation context — skip silently otherwise
  • Discovery: conversation context only, no filesystem search
  • Format: filter out no content extracted entries; Contributing files lists skill files, not research topic files
  • Attribution happens after skill content is written (Step 5), so the agent knows what files were produced
  • source_keys in SKILL.md and references/*.md frontmatter links back to slugs in references/sources.md
  • references/*.md files also get source_keys frontmatter, mirroring research topic file format
  • skill-audit validation of the chain deferred to issue #8
## Summary `/skill-write` accepts research docs as prerequisites but never records them as sources. Skills built from `/research` output have no provenance chain from upstream docs → research files → skill is silently broken. ## Steps to reproduce 1. Run `/research agentskills.io plugins/kyberforge/docs/research/docs/agentskillsio/` — produces topic files + `sources.md` 2. Run `/skill-write` with those research docs as input 3. Inspect the output — no provenance present ## Root cause **Missing skill-write step** — `skill-write` has no step/template instructing the agent to read the research `sources.md` and create sources.md files for the skill. ## Solution Agreed approach from grill session (2026-06-26): **Convention: `references/sources.md` + `source_keys` frontmatter** The provenance chain mirrors the research skill's output format: - `/research` writes `sources.md` to plugin-level docs (e.g. `plugins/<plugin>/docs/research/docs/<topic>/`) - `/skill-author` reads those docs and records provenance in the new skill **Changes to `skill-author`:** 1. **`assets/templates/references/sources.md`** — new scaffold template mirroring the research `sources.md` format exactly (slug → URL, Description, Contributing files, Status). One placeholder entry with `FILL IN:` values. Comment instructs: fill in after writing skill files, or delete if no research was provided. 2. **`assets/templates/SKILL.md`** — add `source_keys` as a commented-out optional field under `metadata`, same treatment as `license` and `compatibility`. 3. **`SKILL.md` (skill-author itself)** — new Step 5 in the "Creating a new skill" flow: - If research `sources.md` is in conversation context: filter to `extracted` entries, populate `references/sources.md` with `Contributing files` pointing to skill files (not research topic files); add `source_keys` to `SKILL.md` metadata and to each `references/*.md` file - If no research sources in context: delete `references/sources.md` - Current Step 5 (validate) becomes Step 6 **Key design decisions:** - Trigger: only when research `sources.md` is present in conversation context — skip silently otherwise - Discovery: conversation context only, no filesystem search - Format: filter out `no content extracted` entries; `Contributing files` lists skill files, not research topic files - Attribution happens after skill content is written (Step 5), so the agent knows what files were produced - `source_keys` in SKILL.md and `references/*.md` frontmatter links back to slugs in `references/sources.md` - `references/*.md` files also get `source_keys` frontmatter, mirroring research topic file format - `skill-audit` validation of the chain deferred to issue #8
Defame1297 added this to the Kyberforge basics milestone 2026-06-25 20:06:00 +00:00
Claude changed title from bug: skill-write loses source provenance — research output not recorded in SKILL.md frontmatter to bug: skill-author loses source provenance — research output not recorded in skill references 2026-06-26 20:37:52 +00:00
Defame1297 removed the
Status
Need More Info
2
 label 2026-06-26 20:45:45 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Enhancement
Priority
Critical
1
Reviewed
Confirmed
1
Milestone
No items
No Milestone Kyberforge basics
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#4
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?