SwarmCraft
Build and shipGuide

Docs

Use SwarmCraft AI skills

Choose the right SwarmCraft skill, invoke it in Copilot, Codex, or Claude Code, and understand how the operator workflow relates to developer-oriented skill collections.

Use SwarmCraft AI skills

SwarmCraft AI skills give you a small vocabulary for directing operational and software work. You choose an outcome such as work, discover, prototype, plan, build, check, or review. The skill gives your AI assistant the detailed workflow, boundaries, and evidence requirements.

SwarmCraft skills give operator-builders a vocabulary for directing software development without requiring them to learn software engineering.

You still own the problem, business rules, priorities, and approval. The AI still needs to apply appropriate architecture, testing, security, design, and implementation practice underneath.

How to invoke a skill

Choose GitHub Copilot, Codex, or Claude Code with SwarmCraft: Choose AI Provider. Start or reconcile your chosen workflow in a trusted repository to install its matching adapters:

  • Copilot commands begin with /, such as /do task=<packet-path>.
  • Claude Code skills use .claude/skills/ and commands such as /swarmcraft-do task=<packet-path>.
  • Codex skills begin with $swarmcraft-, such as $swarmcraft-do task=<packet-path>.

For normal board work, use the extension's Copy SwarmCraft Command, Copy Plan Command, or Copy Test Command action. It supplies the correct provider syntax and packet path. Paste the copied command into your AI chat.

Specialist skills can be invoked directly when their purpose applies. The seeded skill, not this summary, is the authority for its required inputs, safety checks, files, and completion rules.

Choose the right skill

SkillGuiding question
workWhat do I need to get done, and what do we learn while doing it?
importHow do we register this evidence and retrieve a reliable searchable copy?
handbookWhich reviewed knowledge should appear in this dated snapshot?
automateCan this bounded piece of work run reliably with appropriate review and recovery?
formaliseWhat application opportunity is supported by our reviewed operational evidence?
discoverWhat do we actually need, and what evidence supports it?
spend-analysisWhat are our existing software and services costing us?
designHow should this look, feel, and behave?
prototypeWhat do we need to make tangible before we commit?
planWhat exactly are we going to build?
doWhat approved work are we ready to build?
testDoes it behave as intended in realistic scenarios?
checkIs the implementation complete, sound, and supported by evidence?
reviewIs it good enough to approve and move to Done?
merge-requestIs this completed work ready to submit for integration review?
merge-reviewCan the named reviewer accept this revision and authorise its merge?
merge-respondHow should we address the reviewer’s findings and prove the fixes?
securityWhat risks matter here, and how should we address them?
changeWhat will this change affect, and how can we introduce it safely?

For project packets, human approval happens during review. Once the review is approved, the SwarmCraft extension moves the packet to Done. test, prototype, design, and security support delivery when the work needs them. They do not replace the packet or create extra board lanes. change is an advisory pre-deployment assessment. discover and spend-analysis belong to the earlier discovery path.

Operate seeds five skills together. Start with Use Operate to capture your work for a complete first task, after machine and provider setup.

  • Work completes a useful task and saves supported facts, meanings and procedures. It can extend record tables and their matching schema definitions when the work needs them.
  • Import registers new evidence and creates bounded searchable copies with provenance. Imported claims stay untrusted until reviewed; private originals can remain local.
  • Handbook creates an explicitly requested dated snapshot of selected reviewed knowledge and images. It preserves uncertainty and reports each output format's actual result.
  • Automate assesses whether a bounded step can become a tested local helper with a dry run and recovery. One useful example can be enough evidence, but review and verification still apply.
  • Formalise selects reviewed knowledge for a bounded application opportunity. That selection does not upload the repository or change operational authority.

You review operational meaning; the agent maintains schema/, record tables, knowledge navigation and the records diagram. Terminology lives in records/terminology.csv. Decisions and exceptions live in knowledge notes. Imports and exports use dated batches, including ignored files.

Operate skillCodexGitHub CopilotClaude Code
Work$swarmcraft-work/work/swarmcraft-work
Import$swarmcraft-import/import/swarmcraft-import
Handbook$swarmcraft-handbook/handbook/swarmcraft-handbook
Automate$swarmcraft-automate/automate/swarmcraft-automate
Formalise$swarmcraft-formalise/formalise/swarmcraft-formalise

Discovery and project skills are added by their respective workflows; not every skill in the reference table is installed in every repository.

The review skill organizes the diff, evidence, risks, and open decisions, then records the person's decisions through the human review and approval process.

Merge skills

The three merge skills work on completed initiatives, agreed phase ranges or direct packets. They record submission, reviewer decisions and feedback in .reviews/<submission-slug>/. They do not create board lanes or replace task-level review. See Submit and review merge requests for the full loop.

SkillCodexGitHub CopilotClaude Code
Merge request$swarmcraft-merge-request/merge-request/swarmcraft-merge-request
Merge review$swarmcraft-merge-review/merge-review/swarmcraft-merge-review
Merge respond$swarmcraft-merge-respond/merge-respond/swarmcraft-merge-respond

Project guidance template set 15 adds these skills. Upgrade installed tooling to a release containing that bundle, then reconcile the repository guidance. Existing owner edits remain conflicts to review.

The plan skill records the developer, source branch and merge target. Planning alone does not switch branches; authorised implementation prepares the working branch. All phases normally stay on that branch until integration. A direct packet records equivalent Delivery notes without needing an initiative plan.

Why SwarmCraft skills are different

Many AI skill collections encode software-engineering practices such as architecture, testing, security, and code review. They help developers give an AI better engineering instructions.

SwarmCraft starts with the operator's intent. Operator-builders and domain experts can direct work using outcomes such as discover, design, prototype, plan, do, test, check, review, and change. The AI still applies the appropriate engineering practices underneath.

An experienced developer might say:

Use TDD, review the architecture, check the API boundaries, and run a security audit.

An operator-builder should be able to say:

We understand the problem. The prototype looks right. Plan it, build it, prove it works, and show me what needs my approval.

SwarmCraft does not replace good engineering practice. It gives the person who understands the problem control over the outcome, evidence, and approval without requiring them to become a software engineer.

Repair missing or stale skills

For project guidance, run SwarmCraft: Update Repo Guidance. Missing or unchanged generated files are updated, owner edits are preserved as reported conflicts, and the project-guidance diff remains for normal review and commit.

For an Operate repository, run SwarmCraft: Start or Reconcile Operate after signing in. Validated seed changes receive a scoped automatic local commit; ignored data, owner-edited records, and unrelated staged work are excluded. Nothing is pushed. If Git identity, signing, or a hook prevents the checkpoint, fix Git and rerun; the files are preserved. Reload the workspace when prompted after Codex skill changes. Use Continue Work to copy the command for the repository's seeded provider.

Operate skills also checkpoint approved work locally. Use safe inputs: .gitignore excludes files, not sensitive rows inside tracked records, and cannot erase previous commits. AI-provider processing is separate from content-free SwarmCraft seed telemetry; do not assume local work means all inputs stay on your machine.

For everyday operational work, continue with Use Operate to capture your work. For application delivery, continue with Deliver with SwarmCraft in VS Code for the interactive packet workflow, or deliver with the one-shot CLI for a bounded experienced-operator run.