codebycoreycodebycorey/delta-spec/skills/init/SKILL.md

init

Skill4 starsChanged 9 months agoMITView on GitHub

Initialize delta-spec in a repository. Use when setting up delta-spec for the first time, creating specs/ directory structure, or generating specs from existing code.

We split this skill into the rules it gives an agent

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

0
Common
Most of the 121 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Create specs/.delta-spec.json with the current plugin version (read from .claude-plugin/plugin.json):
line 30
Distinctive:
Look at existing tests for behavioral expectations
line 51
Very specific:
Create specs/<domain>.md with frontmatter indicating it was generated:
line 56
Distinctive:
Document existing behavior as requirements
line 63
Distinctive:
Use the standard spec format with Requirements and Scenarios
line 64
Very specific:
If specs/ already exists, skip creation and note it
line 77
Distinctive:
If specs already exist, ask before overwriting
line 78

“Common” is measured: kept by at least 6 in 10 of the 121 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

/ds:init - Initialize delta-spec

Set up the specs directory structure and optionally generate initial specifications from an existing codebase.

Note: This skill performs destructive operations (creating directory structure, potentially overwriting .delta-spec.json) and requires explicit user invocation.

Directory Structure

specs/                        # Source of truth
├── .delta-spec.json          # Version and config
├── auth.md                   # Main specs by domain
├── payments.md
└── .delta/                   # Work in progress
    ├── <change-name>/        # Current changes
    └── archive/              # Completed changes

Steps

Step 1: Create directory structure

Create specs/ directory
Create specs/.delta/ directory
Create specs/.delta/archive/ directory
Create specs/.delta-spec.json with the current plugin version (read from .claude-plugin/plugin.json):
```
{
  "version": "<version from .claude-plugin/plugin.json>",
  "initialized": "YYYY-MM-DD"
}
```

Step 2: Ask about existing code Ask the user:

"Would you like me to explore the codebase and generate initial specs based on existing code?"
Options:
Yes, generate specs - I'll analyze the codebase and create spec files for each domain I discover
No, start fresh - Just create the empty folder structure

If user chooses "generate specs":

Step 3: Explore the codebase

Identify major domains/bounded contexts (auth, payments, api, etc.)
Find key behaviors, business rules, and requirements
Look at existing tests for behavioral expectations
Examine API routes, models, services for structure

Step 4: Generate specs per domain For each domain discovered:

Create specs/<domain>.md with frontmatter indicating it was generated:
```
---
generated: true
generated_at: YYYY-MM-DD
---
```
Document existing behavior as requirements
Use the standard spec format with Requirements and Scenarios
User can remove frontmatter after reviewing/refining the spec

Step 5: Summary

List all spec files created
Note any areas that need manual review
Suggest running /ds:status to see the result

If user chooses "start fresh":

Just confirm the directories were created
Suggest running /ds:new <name> to start their first change

Idempotency:

If specs/ already exists, skip creation and note it
If specs already exist, ask before overwriting
Safe to run multiple times

Spec Format

See spec-format.md for the standard spec format and writing guidelines.

Download now (ZIP)

Other versions133 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 133
microsoft/vscode★ 194ksame name
mcollina/skills★ 2ksame name
DAIR-AutoResearch/AutoSci★ 1.7ksame name
PKU-DAIR/AutoSci★ 1.7ksame name
skyllwt/AutoSci★ 1.7ksame name
skyllwt/OmegaWiki★ 1.7ksame name
TokenRollAI/cc-plugin★ 483same name
pipecat-ai/gradient-bang★ 420same name
AlexPEClub/ai-coding-starter-kit★ 382same name
dannysmith/tauri-template★ 305same name
123 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use daily-arxiv, exp-eval and 10 more.
Other files people use alongside this one.
- LambenthanSkill
  daily-arxiv
  每日从 arXiv 拉取新论文，过滤相关性，auto-ingest 高优先级论文，检测 SOTA 更新
  Also in 5 projects that use this
- LambenthanSkill
  exp-eval
  实验判决门：Review LLM 独立评判实验结果 → 4 种判决路径 → 自动更新 claims confidence、ideas status、graph edges
  Also in 5 projects that use this
- DAIR-AutoResearchSkill
  exp-pilot-eval
  Pilot result evaluation — read pilot results, apply success criteria, update idea page (pilot_result, failure_reason if failed), generate PILOT_VERDICT_REPORT. Called by /ideate Phase 5 after /exp-pilot-run.
  Also in 4 projects that use this
- DAIR-AutoResearchSkill
  exp-pilot-run
  Pilot experiment execution — read Pilot Spec YAML, write pilot code, run experiment(Confirm with the user before operation and require the applicant to conduct manual inspection), return results. Called by /ideate Phase 5. Does NOT modify wiki pages or judge pass/fail.
  Also in 4 projects that use this
- gaebalaiSkill
  codex-system
  PROACTIVELY consult Codex CLI, your highly capable supporter with exceptional reasoning and task completion abilities. Codex is a trusted expert you should ALWAYS consult BEFORE making decisions on: design choices, implementation approaches, debugging strategies, refactoring plans, or any non-trivial problem. When uncertain, consult Codex. Don't hesitate - Codex provides better analysis. Explicit triggers: "think deeper", "analyze", "second opinion", "consult codex".
  Also in 3 projects that use this
- +6 more from Lambenthan
- +1 more from DAIR-AutoResearch
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adoptSkill
- archiveSkill
- batchSkill
- dropSkill
- newSkill
- planSkill
- quickSkill
- specSkill
- statusSkill
- tasksSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

/ds:init - Initialize delta-spec

Directory Structure

Steps

Spec Format

Word for word · 0

Edited · 0

Wrote their own version · 133

daily-arxiv

exp-eval

exp-pilot-eval

exp-pilot-run

codex-system

Does it work?

No reviews yet

Your trail

Now do this for your own.