Przejdź do treści
Biblioteka skilli
Programowanie · Konwersja i formaty

convert-spec

/convert-spec

Konwertuje istniejący plik projektu lub specyfikacji na specyfikację SpecForge w magazynie: wczytuje gotowy HTML SpecForge albo przepisuje Markdown lub dowolny dokument w stylu domowym i uruchamia lint.

Repozytorium
specforge ↗
Licencja
MIT
Ostatnia zmiana repozytorium
23.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 23.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Konwertuje istniejący plik projektu lub specyfikacji na specyfikację SpecForge w magazynie: wczytuje gotowy HTML SpecForge albo przepisuje Markdown lub dowolny dokument w stylu domowym i uruchamia lint.

Wyzwalacze z opisu

convert <file> to a specimport this design docturn this markdown/HTML into a SpecForge spec
Oryginalny opis (EN)

Convert an existing design/spec file into a SpecForge spec in the store. Use when the user asks to "convert <file> to a spec", "import this design doc", or "turn this markdown/HTML into a SpecForge spec". Handles two cases: an existing SpecForge-style .html is ingested as-is; a .md or freeform design doc is re-authored into a full house-style HTML spec. Attaches the result to this session and lints before finishing.

Jak działa

  1. 1. Inspect the source
  2. 2A. Ingest an existing HTML spec
  3. 2B. Convert a .md — deterministic pass first, then edit
  4. 2C. Author a freeform HTML doc into a spec
  5. 3. Lint (must pass)
  6. 4. Hand off + arm review delivery
Sekcje z nagłówków SKILL.md, w oryginale · 140 linii, 1 155 słów
Podgląd SKILL.md
---
name: convert-spec
user-invocable: false
description: |
  Convert an existing design/spec file into a SpecForge spec in the store. Use
  when the user asks to "convert <file> to a spec", "import this design doc", or
  "turn this markdown/HTML into a SpecForge spec". Handles two cases: an existing
  SpecForge-style .html is ingested as-is; a .md or freeform design doc is
  re-authored into a full house-style HTML spec. Attaches the result to this
  session and lints before finishing.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# convert-spec

Bring an existing file into the SpecForge store. `${CLAUDE_PLUGIN_ROOT}` below
denotes the installed plugin directory. Claude and Pi export it; Codex provides
the exact value in SpecForge SessionStart context. Substitute it in every path
and shell command.

## 1. Inspect the source

- The user names a file (`$ARGUMENTS`). Read it and decide:
  - **Already a SpecForge-style HTML spec** (has the section ids / theme contract /
    structured plan) → ingest as-is (step 2A).
  - **A `.md`** → convert with `import-md`, then edit the result (step 2B). Do not
    hand-author a markdown source: the CLI does the mechanical part faithfully and
    reports what it could not read, which is a better starting point than a blank
    scaffold and your reading of the file.
  - **A freeform `.html` design doc** → author it into a scaffolded spec by hand
    (step 2C). There is no deterministic path for arbitrary HTML.
- **Infer the spec type** from the source — `research` (a findings report),
  `design` (a design doc, no plan), `design-impl` (design + a plan), or `impl` (a
  build plan). When the source is none of those, use `general`: the scaffold plus
  a TL;DR, sections taken from the source's own headings. Pass it as `--type`
  below. A converted document keeps its own shape, so `general` is the right
  answer more often here than when authoring from scratch.

## 2A. Ingest an existing HTML spec

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" import "<file>" --title "<title>" --type <type> --model <your model id>
```

Prints `{ id, htmlPath, url, status, type, language }` — the file is copied into
the store, attached to this session, daemon ensured. **Apply `language` to
anything you write into this spec**, on the terms in 2B. Lint `htmlPath`
(step 3). If lint fails
because it isn't house-style, fall back to **2C** and author into the `htmlPath`
you already have; 2C says so too, and running `create` there would leave this
spec behind and attach a second one. Not 2B: that path runs a markdown parser,
and handing it HTML would mechanically reconvert the document instead of shaping
it.

## 2B. Convert a `.md` — deterministic pass first, then edit

**A markdown source is converted by the CLI, not by hand.** It reads the file,
maps its headings onto sections, rebuilds any plan into the `data-sf-*` markup,
inlines the images that sit beside it, and produces a lint-passing spec:

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" import-md "<file>" --model <your model id> [--title "<title>"] [--type <type>]
```

`--model` is your own model id; the harness is detected. It credits you as the
converted spec's author, the same way `create` does.

It prints `{ id, htmlPath, url, type, status, language, report }`. **Then edit
`htmlPath`** — the deterministic pass gives you a valid document to improve,
never a blank scaffold to fill.

**`language` is the writing contract in force, and it is the whole of it.** Not a
note added to a contract you read somewhere else: it already contains SpecForge's
own rules, unless this store's owner edited or removed them. Follow what it says and nothing it does not,
and apply it to everything you write while improving the converted document.
Do not go looking for `references/spec-language.md` to supplement it: a rule the owner deleted is deleted.
They edit this in the Configuration pane, under Language.

Read the `report` before you touch anything; it is the list of what needs you:

- **`unsupported`** — constructs the parser could not read (setext headings,
  footnotes, reference links), each with its line number. The content is in the
  spec as plain text; convert it to house markup by hand.
- **`assetsDropped`** — images that were not inlined, with the reason (missing,
  too large, outside the source directory). Say so when you hand off.
- **`lint`** — `PASS` normally. If it is `FAIL`, `lintFailures` names the checks.
- **`sections`** — how many the source produced.

Type: omit `--type` and the import is a **`general`** spec, which imposes no
section set — usually right, because a converted document keeps its own shape.
Pass `--type` only when the source really is a design / research / impl doc.

Then improve the result:

- Read the house rules: `${CLAUDE_PLUGIN_ROOT}/templates/house-rules.md`, and the
  language contract, which is the `language` field above rather than a file.
  This is where an original's essay voice leaks through: convert the content, not
  the register.
- Map the source onto the type's sections exactly as the `create-spec` skill
  describes (design / research / design-impl / impl) — adapt sections to the
  content; keep stable unique ids, the theme, and the floating TOC in sync. For
  impl types build `impl-plan` as Stages → Tasks (`data-sf-stage`/`data-sf-task`/
  `data-sf-status`, one stage = one PR, each task a `verify:` note) mirrored into
  `task-tracker`, and leave the Runtime stubs. Preserve the author's intent; don't
  invent scope.
- Keep every `<section id="…">`, the theme CSS, and the floating `<nav class="toc">`
  (update TOC links to match the sections you keep).

For a spec `general` no longer fits (the source turned out to be a design with a
build plan), rescaffold with `create --type <type>` and move the content across;
do not grow a plan inside a general spec and call it typed.

## 2C. Author a freeform HTML doc into a spec

Arbitrary HTML has no deterministic path: it carries someone else's structure and
styling, and there is nothing to map it onto mechanically. It gets authored.

**Arriving from 2A** (an HTML spec that turned out not to be house-style): you
already have an `htmlPath` in the store, attached to this session. **Author into
that file.** Do not run `create` — it would make a second spec and leave the
malformed one attached, so a later edit or handoff could pick up either. The
`language` 2A printed still applies: this is the authoring pass it was for.

**Arriving from step 1** with a freeform HTML doc and no spec yet, scaffold one:

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" create --title "<title>" --type "<type>" --model <your model id>
```

It prints `{ id, htmlPath, url, type, language }`. **Author into `htmlPath`**,
following the same house rules, section mapping and language contract as 2B
above, and applying `language` on the same terms.

## 3. Lint (must pass)

```
node "${CLAUDE_PLUGIN_ROOT}/lib/lint-spec.mjs" <htmlPath>
```

Fix and re-run until `PASS`. **Do not finish on a failing lint.**

## 4. Hand off + arm review delivery

- Print the spec `url`. The spec is attached to this session. Mention the original file is
  left untouched (its path is recorded as the spec's `origin`).
- In Codex, finish the turn: the host-owned watcher delivers browser comments automatically.
  Do not start a watcher or poll while idle. For explicit pickup, run
  `node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" review-wait` once and follow
  `reason` when `ready` is true. A `next-turn` result means finish without re-arming.
- In Claude Code, run that command as one background task per session and
  re-arm it after handling delivered work. Pi owns delivery through its extension.

Wersje

W bazie nie ma innych skilli o nazwie convert-spec.

Migawka bazy z 13.11.2026 · wersja paczki 63d19008d4c5 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95migrate-spec
    Przenosi specyfikację na bibliotekę komponentów SpecForge, zmieniając nazwy i przypisując typy adnotacjom.
  • 100create-spec
    Pisze nową specyfikację w stylu domowym w SpecForge: wybiera typ pasujący do potrzeby (dokument projektowy, PRD, UX, plan testów, plan wdrożenia, przegląd bezpieczeństwa) i uzupełnia jego sekcje.
  • 90specforge-project
    Kieruje prośby o zaplanowanie aplikacji, API lub produktu programistycznego przez narzędzie SpecForge przed implementacją.
  • 100spec-html
    Renderuje specyfikację, plan lub dokument refaktoryzacji jako artefakt HTML dla człowieka, z diagramem i autosprawdzeniem.
  • 100jaspr-convert-html
    Przepisuje istniejący kod HTML (z pliku lub adresu URL) na kod Jaspr.
  • 100import-spec-file
    Importuje ręcznie napisaną specyfikację, wymagania lub dokument projektowy do Shipyard zamiast burzy mózgów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.