[Bug]: Generic escape hatch does not support SKILL.md rendering

[mnriem]

Bug Description

The generic escape hatch does not support SKILL.md rendering

Steps to Reproduce

No possible to use specify init to render SKILL.md files with --integration generic

Expected Behavior

Get the generic SKILL.md files

Actual Behavior

Not possible to do

Specify CLI Version

1.0.6

AI Agent

Not applicable

Operating System

macOS

Python Version

Pyton 3.13

Error Logs

Additional Context

No response

[github-actions]

Bug assessment — generic-skill-rendering: Likely valid, needs reproduction · severity low

---

Bug Assessment: Generic escape hatch does not support SKILL.md rendering

• Slug: generic-skill-rendering
• Created: 2026-09-12T14:10:04Z
• Source: issue [Bug]: Generic escape hatch does not support SKILL.md rendering #4561
• Verdict: likely valid, needs reproduction
• Severity: low

Report (summarized)

The reporter says that specify init cannot use the generic integration to render SKILL.md files. They expect generic integration output in the skills format, but report that the available generic flow does not provide it. The report gives Spec Kit CLI version 1.0.6, macOS, and Python 3.13, with no error log and no follow-up comments.

Symptom

The generic integration currently scaffolds Markdown command files in a caller-selected --commands-dir; it has no documented mode or option that produces speckit-<name>/SKILL.md directories. A user targeting an unlisted skills-based agent therefore cannot use the generic escape hatch for that agent's expected file format. The report does not specify the desired skills root directory, invocation syntax, or exact command used, so the requested behavior is not fully reproducible from the issue alone.

Reproduction

1. Run specify init <project> --integration generic --integration-options="--commands-dir <path>".
2. Inspect the generated files under <path>.
3. Observe that the generic integration writes speckit.<command>.md files and exposes no --skills/skills-directory option for generating speckit-<command>/SKILL.md files.

[NEEDS CLARIFICATION: exact command invocation, desired skills directory, and whether the target agent expects project-local or global skills.]

Suspected Code Paths

• src/specify_cli/integrations/generic/__init__.py:13,17-33 — GenericIntegration subclasses MarkdownIntegration and hard-codes Markdown registrar metadata (format: markdown, .md extension, $ARGUMENTS). It declares only the required --commands-dir option.
• src/specify_cli/integrations/generic/__init__.py:99-147 — setup() resolves one command directory, processes templates as Markdown, and writes flat speckit.<command>.md files. It never derives skill names or creates SKILL.md files.
• src/specify_cli/integrations/base.py:1603-1880 — SkillsIntegration contains the separate skills implementation: skills_dest(), speckit-<name> directory naming, normalized skills frontmatter, and SKILL.md output. Generic does not inherit or invoke this path.
• docs/reference/integrations.md:49 — the documented generic integration contract describes a user-provided commands directory for command files, but does not advertise skills output.
• tests/integrations/test_integration_generic.py:1-311 — generic integration tests assert Markdown files and a --commands-dir requirement; there is no generic skills-mode coverage.

Root Cause Hypothesis

The generic integration was intentionally implemented as a Markdown-only escape hatch, while skills rendering is a distinct base-class workflow that assumes a configured static skills root. Consequently, the reported output is consistent with the current implementation rather than a runtime failure. The capability gap is high-confidence; whether it is a bug or an enhancement depends on the intended contract for generic integrations and the target agent's required skills location.

Proposed Remediation

Preferred: Define an explicit generic skills mode rather than changing the existing Markdown behavior implicitly. Add a mutually exclusive --skills-dir <path> (or an equivalent clearly named option) alongside --commands-dir, make the generic integration select the output mode from parsed options, and reuse the shared SkillsIntegration rendering logic or extract its format-rendering portion into a reusable helper. Preserve the existing commands-dir behavior for compatibility, validate that the selected destination remains inside the project root, and persist the selected option so upgrade/uninstall can address the same files.

Update the integration reference to document both layouts, including the expected skill invocation convention and any limitations for agents that require a global skills directory. Add a clear CLI error when neither option or both mutually exclusive options are supplied.

Alternatives (optional):

• Add a dedicated generic skills integration key or a generic integration option such as --format skills. This makes the mode explicit but may create a second registry entry and complicate configuration persistence.
• Keep generic Markdown-only and document that unsupported skills-based agents require a first-class/community integration. This avoids implementation complexity but does not satisfy the reported escape-hatch use case.

Files likely to change:

• src/specify_cli/integrations/generic/__init__.py
• src/specify_cli/integrations/base.py or a new shared skills-rendering helper
• tests/integrations/test_integration_generic.py
• docs/reference/integrations.md
• Any integration option persistence/upgrade tests or code reached by the selected-mode configuration

Tests to add or update:

• Generic skills mode creates one speckit-<command>/SKILL.md per command with valid required frontmatter and processed script placeholders.
• Generic Markdown mode remains unchanged.
• Missing, conflicting, blank, and path-escaping mode/directory options fail with actionable errors.
• Install/uninstall and upgrade preserve and remove the selected skills layout safely through the manifest.
• CLI inventory coverage includes the new generic skills output.

Risks & Considerations

• Introducing a new mode affects persisted integration options and must not cause an upgrade or uninstall to target the wrong layout.
• Skills agents differ in invocation prefixes and may use project-local versus global roots; generic mode cannot infer those conventions, so the option contract must require enough information from the user.
• Reusing SkillsIntegration directly may require refactoring because its current configuration expects a static config["folder"], whereas generic paths are supplied at runtime.
• The issue reports version 1.0.6 while this checkout contains a later implementation; the behavior should be reproduced against the reporter's version and current release before implementation.

Open Questions

• [NEEDS CLARIFICATION: What exact specify init command and --integration-options were used?]
• [NEEDS CLARIFICATION: What skills root should generic mode write to, and should it be project-local or global?]
• [NEEDS CLARIFICATION: What invocation syntax does the target agent require (/speckit-..., $speckit-..., or another form)?]
• [NEEDS CLARIFICATION: Is the request intended as a bug fix to an existing documented contract, or as a new generic skills feature?]

Generated by 🐛 Assess Bug from Labeled Issue for #4561 · copilot · gpt52codex · 2.75 AIC · ⌖ 6.46 AIC · ⊞ 25.5K · ◷