konveyor / konveyor/agentic-controller

ADR: Doc-to-skill authoring: generate SKILL.md from user migration docs

Open
#158 0 comments 0 reactions 1 assignee Claimed by @savitharaghunathan View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.