konveyor / konveyor/agentic-controller
ADR: Doc-to-skill authoring: generate SKILL.md from user migration docs
- Dominant language
- Go
- Stars
- 2
- Forks
- 12
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 41
Description
## Context
Split out from #32, which originally bundled three questions about
skill UX. The runtime-discovery question (Q1) is resolved by ADR 0014
(goose discovers skills natively via the linked `~/.agents/skills`
root) and tracked separately in #70. This issue carries forward the
remaining, still-open half of #32: doc-to-skill authoring.
## Problem
Skill authoring is a non-goal of the current skill-mounting work, but
without a mechanism to turn a migration doc into a skill, we assume
users already have skill-authoring knowledge. That's the same
barrier-to-entry problem we have with rules creation. Users have
domain expertise (their internal migration documentation) but not
necessarily the expertise to shape it into an AgentSkills.io skill.
## Proposal (carried forward from #32)
Add doc-to-skill authoring support that:
- Accepts user-provided migration documentation as input
- Generates a well-formed skill (a `SKILL.md` with valid AgentSkills.io
frontmatter) from it
- Packages it as a SkillCard source (image, git, or inline per ADR
0015)
### Note on ADR 0015
The original proposal in #32 described generating `SKILL.md` +
`skill.yaml`. ADR 0015 deletes `skill.yaml` entirely — `SKILL.md`'s
YAML frontmatter (`name`, `description`, and the other
AgentSkills.io-allowed fields) is now the only skill metadata. Any
authoring tool should generate frontmatter-only output and can
validate it with `konveyor-skills validate ` (ADR 0015 §6).
## Open questions
- Where does this tool live — CLI, a step in the platform UI, or both?
- Does authoring need to be interactive (iterate with the user on the
generated skill) or one-shot?
- How does a generated skill get from a local directory into a
SkillCard (`inline` for a quick draft vs. `image`/`source` for
something durable)?
## References
- #32 (original issue, now scoped to runtime discovery only)
- #70 (runtime discovery spike/fix)
- ADR 0014 (skill loading and prompt assembly)
- ADR 0015 (skill packaging and delivery — `skill.yaml` removed)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.