SWE Init

What This Skill Does

Use this skill to establish an optional repo-local preference layer for how agents should collaborate in a specific repository.

The job is to:

• gather a short set of behavior-shaping preferences
• write them to

  .ai/swe.json

  as minified JSON
• keep the file local-first while allowing the user to commit it if they want
• define how later skills should consult the file safely

This skill is not a general repository bootstrapper. It configures agent collaboration defaults, not the project's runtime or package setup.

When To Use

Use this skill when the user wants to:

• initialize repo-local agent settings
• create a small preference file for how agents should work in this repo
• run a quick-start setup with opinionated defaults
• make later

  swe:

  skills respect local collaboration preferences

Do Not Use

Do not use this skill for:

• npm init

  ,

  pnpm init

  , or similar project scaffolding
• dependency installation or toolchain bootstrap

• .env

  , secret, or credential setup
• committed team policy unless the user explicitly wants the file checked in
• broad repo documentation or agent-guidance rewrites unrelated to the local preference layer

Inputs To Confirm

Confirm or infer:

• whether the user wants full interview mode or quick mode
• whether

  .ai/swe.json

  already exists
• whether

  .gitignore

  should be updated
• whether any sensitive paths should trigger extra caution

If the user asks for quick mode, skip the interview entirely.

If

.ai/swe.json

already exists, do not overwrite it silently. Ask whether the user wants to keep it, edit it, or replace it.

Preference Contract

The preference file path is fixed:

• .ai/swe.json

The file format is fixed:

• minified JSON
• include

  "v": 1

• store only values that differ from the built-in defaults
• keep keys compact but legible

Use this schema:

• v

  : schema version

• autonomy

  :

  bounded

  ,

  ask

  , or

  assertive

• plan

  :

  minimal

  ,

  short

  , or

  design

• scope

  :

  minimal

  ,

  balanced

  , or

  broad

• verify

  :

  narrow

  ,

  standard

  , or

  broad

• report

  :

  terse

  ,

  evidence

  , or

  full

• alts

  :

  material

  or

  usually

• paths

  : array of sensitive path strings

Do not write prose, Markdown, YAML, or duplicated default values.

Built-In Defaults

Treat these as internal defaults, not required file contents:

{"v":1,"autonomy":"bounded","plan":"short","scope":"minimal","verify":"standard","report":"evidence","alts":"material","paths":[]}

That means quick mode should normally write:

{"v":1}

Precedence Rule

Later skills should apply preferences in this order:

1. explicit user request
2. repository guidance such as

   AGENTS.md

   or

   README.md

3. .ai/swe.json

4. the skill's own defaults

Skills should consult

.ai/swe.json

only when the preference would materially change behavior, such as planning, edit scope, validation, or reporting. A missing or malformed file should fall back safely instead of blocking work.

Instructions

Step 1: Inspect The Current State

Check whether:

• .ai/

  exists

• .ai/swe.json

  exists

• .gitignore

  exists

If an existing preference file is present, read it before proposing any write.

Step 2: Choose The Right Entry Path

If the user asked for quick mode, follow quick mode.

If the user asked for a normal setup, run the short interview.

If the request is actually about project scaffolding or runtime bootstrap, redirect instead of forcing this skill.

Step 3: Run The Short Interview Only When Needed

In full mode, ask one question at a time and keep the interview short.

Capture only preferences that materially change agent behavior:

1. autonomy

2. plan

3. scope

4. verify

5. report

6. alts

7. optional

   paths

Do not add soft personality questions that do not change execution behavior.

Step 4: Normalize To The Compact Schema

Convert interview answers into the compact schema values.

Write only non-default overrides. For example:

{"v":1,"autonomy":"ask","verify":"broad","paths":["infra/","migrations/"]}

Step 5: Write

.ai/swe.json

Create

.ai/

if it does not exist.

Write

.ai/swe.json

as minified JSON with no trailing explanation in the file.

Never silently replace an existing valid file. If the file is malformed, show the parse problem briefly and ask before repairing or replacing it.

Step 6: Update

.gitignore

Only When Requested

If the user explicitly asks for

--gitignore

or otherwise asks to keep the file local-only, add this exact path if it is not already present:

• .ai/swe.json

Do not ignore the entire

.ai/

directory unless the user explicitly asks for that broader behavior.

Step 7: Summarize The Effective Result

At the end, summarize:

• which mode ran
• which file was written or preserved
• whether

  .gitignore

  changed
• which preferences were set explicitly
• the precedence rule future skills should follow

Output Requirements

Provide a concise result that includes:

1. mode used:

   quick

   ,

   quick --gitignore

   , or

   interview

2. file status for

   .ai/swe.json

3. whether

   .gitignore

   changed
4. the explicit non-default preferences saved
5. the precedence rule
6. any follow-up needed if an existing file was kept or not overwritten

If the request is out of scope, say so directly and redirect to the correct workflow instead of producing a partial init plan.

Examples

Example 1

User says:

Initialize agent settings for this repo and ask me a short questionnaire.

Actions:

1. Check for an existing

   .ai/swe.json

2. Ask the compact interview one question at a time
3. Write only non-default overrides
4. Summarize the resulting local preference layer

Result: The repo gets a small machine-readable preference file without turning into a broader bootstrap workflow.

Example 2

User says:

Run swe:init --quick --gitignore here.

Actions:

1. Check for an existing

   .ai/swe.json

2. Skip the interview
3. Write

   {"v":1}

4. Add

   .ai/swe.json

   to

   .gitignore

   if missing

Result: The repo gets the opinionated defaults in one fast local-first step.

Example 3

User says:

npm init this repo and set up the package.json.

Actions:

1. Recognize that the request is about project scaffolding
2. Do not load this workflow
3. Redirect to the appropriate repo bootstrap work

Result: This skill stays narrow and does not over-trigger on unrelated init requests.

Troubleshooting

Problem:

.ai/swe.json

Already Exists

Do not replace it automatically. Show the current state and ask whether to keep it, edit it, or replace it.

Problem: The Existing File Is Invalid JSON

State that the file is malformed, show the parse issue briefly, and ask whether to repair or replace it. Do not silently discard existing data.

Problem: The User Wants The File Committed

That is allowed. Skip

.gitignore

changes unless the user explicitly asks for local-only storage.

Quality Bar

• Keep the workflow narrow and clearly separate it from project bootstrap
• Use

  .ai/swe.json

  and no alternate path by default
• Preserve local-first behavior without forcing

  .gitignore

  edits
• Write compact, machine-readable JSON only
• Store only non-default overrides
• Never silently overwrite an existing preference file
• Make the precedence rule explicit so future skills can consume the file safely