Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

create-system-spec

/create-system-spec

Przygotowuje specyfikacje systemowe repozytorium: dzieli kod na obszary i zapisuje pliki system-spec.md oraz indeks SYSTEM_SPECS.md.

Repozytorium
kapo-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
30.10.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
4
Skrypty
0
Komentarze HTML
1
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

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

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Przygotowuje specyfikacje systemowe repozytorium: dzieli kod na obszary i zapisuje pliki system-spec.md oraz indeks SYSTEM_SPECS.md.

Oryginalny opis (EN)

Set up system specs in a repo for the first time. Surveys the code with read-only sub-agents, proposes a split by concern, and after approval writes <concern>.system-spec.md files and a root SYSTEM_SPECS.md index, restructures old system_spec.md and *.system-spec.md files into the new format, and relinks AGENTS.md and other rule files. Runs once per repo, then proves the result with maintain-system-spec, which must be installed. Use when the user asks to create, set up, bootstrap, or migrate system specs, or write system specs for a repo with no SYSTEM_SPECS.md. Does not run when SYSTEM_SPECS.

Jak działa

  1. Hard stops
  2. Checklist
  3. Step 1 — Name the repo and check the tree
  4. Step 2 — Inventory
  5. Step 3 — Survey the code
  6. Step 4 — Propose the split
  7. Step 5 — Draft each spec
  8. Step 6 — Write
  9. Step 7 — Prove it
  10. Step 8 — Report
Sekcje z nagłówków SKILL.md, w oryginale · 222 linii, 1 664 słów
Podgląd SKILL.md
---
name: create-system-spec
description: >-
  Set up system specs in a repo for the first time. Surveys the code with
  read-only sub-agents, proposes a split by concern, and after approval
  writes <concern>.system-spec.md files and a root SYSTEM_SPECS.md index,
  restructures old system_spec.md and *.system-spec.md files into the new
  format, and relinks AGENTS.md and other rule files. Runs once per repo,
  then proves the result with maintain-system-spec, which must be installed.
  Use when the user asks to create, set up, bootstrap, or migrate system
  specs, or write system specs for a repo with no SYSTEM_SPECS.md. Does not
  run when SYSTEM_SPECS.md already exists; use maintain-system-spec then.
  Leaves everything uncommitted.
---

# Create system specs

Set up system specs in one repo, once. Survey the code, propose which
concerns get a spec, and stop for approval. Then draft the specs from the
code, write them with the master index, relink every rule file, and prove
the result by running `maintain-system-spec` once. Stop after the report.

Later upkeep, and specs for code that has none yet, belong to
`maintain-system-spec`.

The format is in `maintain-system-spec`:
[format.md](../maintain-system-spec/format.md). Read it before Step 4. This
skill needs `maintain-system-spec` installed. The survey prompt is in
[prompts.md](prompts.md). Why each rule is the way it is:
[DECISIONS.md](DECISIONS.md).

## Hard stops

- Do **not** run when `SYSTEM_SPECS.md` has the line `<!-- system-specs format: 1 -->`. Tell the person to use `maintain-system-spec`, which also adds specs for gaps.
- Do **not** run unless `maintain-system-spec` is installed. Check that [format.md](../maintain-system-spec/format.md) can be read. If not, tell the person to install it, then end the turn.
- Do **not** run unless `HEAD` equals `origin/main` and tracked files have no changes.
- Do **not** draft a spec until the person approves the split. Propose, then end the turn.
- Do **not** let a sub-agent write. Only the main agent writes.
- Do **not** edit product code, except comment lines that name an old spec path or cite a rule by position.
- Do **not** drop a rule from an old spec without listing it in the proposal or the report, with the reason.
- Do **not** commit, push, or open a pull request.
- Do **not** ask the person what the repo can show.

## Checklist

```
Create system specs:
- [ ] Step 1: Name the repo and check the tree
- [ ] Step 2: Inventory existing specs and rule files
- [ ] Step 3: Survey the code in read-only sub-agents
- [ ] Step 4: Propose the split — then stop for approval
- [ ] Step 5: Draft each spec in its own read-only sub-agent
- [ ] Step 6: Write the specs, the master, and the links
- [ ] Step 7: Prove it with maintain-system-spec
- [ ] Step 8: Report, then stop
```

## Step 1 — Name the repo and check the tree

Use the git repository that contains the work in front of you. If several
repos are open, ask which one, then end the turn. Say its `owner/repo`.

Read `SYSTEM_SPECS.md` at the root, if there is one. If it has the format
marker, stop: see Hard stops.

Run `git fetch origin main`. Refuse to run, and say why, unless both hold:

- `HEAD` equals `origin/main`, either on the branch `main` or detached
- `git status --porcelain --untracked-files=no` prints nothing

Tell the person what to run to fix it, then end the turn:

- **No work in progress:** `git switch main && git pull`.
- **Work in progress:** `git worktree add --detach <path> origin/main`, then
  run the skill from `<path>`. Do not create the worktree yourself.

Read only files git tracks: list them with `git ls-files`, not `rg --files`.
Gitignored build output such as `infra/cdk.out/`, `target/`, and `build/`
holds stale copies of source and specs.

## Step 2 — Inventory

List, with paths:

- **Existing specs:** `git ls-files | rg -i 'system[-_]spec'`, and a
  `SYSTEM_SPECS.md` without the marker.
- **Rule files:** `AGENTS.md`, `CLAUDE.md`, `.cursorrules`,
  `.github/copilot-instructions.md`, `.cursor/rules/*.mdc`, and any of these
  in subfolders.
- **Constitution:** `.specify/memory/*.md`.
- **OpenSpec:** `openspec/specs/**`.
- **References to old specs:** `git grep -n -i -e 'system_spec' -e 'system-spec'`.
  These are the lists, links, and comments Step 6 must update. Also note
  references that cite rules by position, such as "invariants 1–2".
- **Source areas:** the tracked source directories, with file and line
  counts (`git ls-files <dir> | xargs wc -l`). Split a directory over about
  50 files or 8k lines one level down. Each area is one survey sub-agent.

## Step 3 — Survey the code

Launch one read-only sub-agent per source area, all at once:

| Tool | Sub-agent |
|------|-----------|
| Cursor | The `explore` type, asked to be "very thorough". Cursor's Task tool has no read-only flag. |
| Claude Code | A read-only agent type, if one is available |
| Anything else | A general sub-agent. The prompt's read-only line is the only guard. |

Give each one the [survey prompt](prompts.md), filled in for its area, with
the existing specs, rule files, and OpenSpec specs that mention it. Wait for
all of them before Step 4.

Read each Files read line. Where a sub-agent read part of its area, note it:
the drafts in Step 5 read those files again.

## Step 4 — Propose the split

Read [format.md](../maintain-system-spec/format.md). Group the rules the
survey found into concerns, using its
[split rules](../maintain-system-spec/format.md#split-rules).

**What comes first.** Propose specs for the 3 to 5 riskiest concerns, plus
every existing spec restructured into the new format. Riskiest means a
broken rule would harm people or money most: authentication and sessions,
payments, personal data, request signing, data other repos rely on. Every other source area goes under `Uncovered`, so later runs of
`maintain-system-spec` can add specs there.

**Existing specs.** Restructure every one into the new format. For each,
say whether it is renamed, merged into another spec, split into several, or
retired because it holds no rules. Name where its rules go. List any real
rule that would have no home, and why.

Show the proposal in this order:

1. **Specs**, one block each: path, concern and one-line purpose, ID prefix,
   Scope globs, source (new, or restructured, merged, or split from which old
   spec), about how many rules, and why it is in the first set.
2. **Old specs:** each old path, and what happens to it.
3. **Rules with no home:** old rules that would be dropped, and why.
4. **Uncovered:** source folders left without a spec.
5. **Links to update:** rule files and the number of code comments and docs
   that point at old spec paths or cite rules by position.
6. **Questions:** only what the code cannot answer, such as whether a
   behavior is intended. Most proposals have none.

Then ask, and end the turn:

**Approve this split, or tell me what to change?**

Change the proposal as asked and show it again until the person approves.

## Step 5 — Draft each spec

Run the Step 1 tree check again first: the person may have changed the
checkout since the proposal.

Launch one read-only sub-agent per approved spec, all at once, with the same
sub-agent type as Step 3. Give each one the
[draft prompt](../maintain-system-spec/records.md#draft-prompt), filled in
from the approved split: its old specs, the rules that move in from other old
specs, and the specs it should link to instead of restating. Sub-agents
return the draft text. They do not write files. Wait for all of them.

**Check each draft:**

- Every rule has an ID with its prefix, an `Enforced by` line, and an
  `Evidence` line that cites `file:line` or says `(inferred)`.
- Nothing the format forbids: signatures, inventories, history, plans,
  `Version` or `Last updated` headers, position references.
- Within the size cap. If a draft overflows, propose a split and wait.
- Every statement in each old spec appears in some draft's Carried list. A
  real rule marked dropped needs a reason the person saw in Step 4, or it goes
  in the report.
- No rule is written in two drafts. Keep it in one and link it from the
  other.

Open the cited code for any rule whose evidence looks doubtful. Step 7 checks
every rule, so you do not need to prove them all here.

## Step 6 — Write

Write in this order. Do not stage or commit anything.

1. **Spec files** at their approved paths.
2. **Old specs:** delete each old spec file once every rule in it is carried,
   merged, or listed as dropped. Use a plain delete or move, not `git mv`,
   which stages the change.
3. **`SYSTEM_SPECS.md`** in the [master format](../maintain-system-spec/format.md#master-index),
   with the format marker. Every row starts at Last verified `never` and
   Last check `—`. List `Uncovered` folders.
4. **Rule files:** in each rule file and constitution, replace any list of
   specs with a link to `SYSTEM_SPECS.md`, as in
   [Links from rule files](../maintain-system-spec/format.md#links-from-rule-files).
   Keep the file's own wording of the obligation.
5. **Other references:** in code comments and docs, replace old spec paths
   with the new spec path, and positions with rule IDs. Change only the
   comment text.

Then run the Step 2 reference search again for every old spec path. Each hit
left is either fixed or listed in the report.

## Step 7 — Prove it

Follow `maintain-system-spec` on demand, naming every new spec. A spec no one
has checked against the code is a draft.

Act on its results as that skill says: it edits stale specs, reports rules
the code breaks as probable bugs, and holds looser changes. It moves Last
verified only for specs it checked in full with no rule broken.

If it is `blocked` because it could not run, fix what blocked it and run it
again once. If it still cannot run, say so in the report.

## Step 8 — Report

In this order, leaving out empty sections:

1. **Specs written:** path, rule count, how many are enforced and how many
   are `unenforced` or `(inferred)`, and Last check.
2. **Code breaks a rule:** from Step 7: rule ID, `file:line`, one sentence.
   These are probable bugs.
3. **Held for confirmation:** from Step 7.
4. **Old specs:** each old path, and where its rules went.
5. **Rules dropped:** old rule and why.
6. **Links updated:** rule files, and how many comments and docs. Any old
   reference left, with its path.
7. **Uncovered:** folders with no spec yet.
8. **Questions:** anything still open.

End with: everything is uncommitted in `<checkout path>`. Create a branch
and commit it through a pull request, for example
`git switch -c docs/system-specs`. From now on, `maintain-system-spec` keeps
the specs current; run it before each pull request.

Then stop.
Pliki w paczce (4)
  • DECISIONS.md 6 KB
  • README.md 3 KB
  • SKILL.md 11 KB
  • prompts.md 2 KB

Wersje

W bazie nie ma innych skilli o nazwie create-system-spec.

Migawka bazy z 13.11.2026 · wersja paczki 3e6e56988e01 (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

  • 100maintain-system-spec
    Sprawdza specyfikacje systemowe repozytorium względem kodu i aktualizuje nieaktualne, a naruszenia zgłasza jako prawdopodobne błędy.
  • 81spec-first
    Prowadzi pracę ze specyfikacjami w repozytorium: tworzy folder .specs, opisuje zmianę, wykonuje kolejne zadanie i synchronizuje specyfikacje.
  • 100spec
    Pisze specyfikację wdrożeniową funkcji w docs/specs z problemem, projektem, plikami i kryteriami weryfikacji, dzieląc ją na części.
  • 90specsmith-init
    Tworzy w projekcie strukturę katalogu specs z szablonami specyfikacji, planu i zadań z zainstalowanej wtyczki Specsmith.
  • 100write-specs
    Tworzy lub doprecyzowuje specyfikację funkcji SPEC SDD przed rozpoczęciem implementacji.
  • 100spec
    Prowadzi interaktywne odkrywanie wymagań i zapisuje pliki specyfikacji, gdy użytkownik prosi o spisanie specyfikacji.

Uwagi i zgłoszenia

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