smaqit-create-skill

name	smaqit.create-skill
description	Generates a compiled SKILL.md file from a name and project context — infers a complete specification covering steps, output, scope, failure handling, and examples; writes a definition file; and invokes smaqit.L2 to produce the final skill artifact. Applies to new skill creation, workflow packaging, domain knowledge encapsulation, and repeatable procedure authoring.
metadata	{"version":"2.1.0"}
allowed-tools	Bash

Create Skill

Steps

1. Gather

Ask the user for the skill name in a single message (lowercase, hyphens allowed, e.g., my-review). The description will be inferred from the name and scanned context.

2. Scan

Before writing anything, read:

• All existing files in .github/skills/ — for patterns and conventions already used in this project
• Project README — for domain and conventions
• Any project manifests that describe workflows or user-facing operations

Also extract any relevant detail the user has already provided in the conversation.

3. Infer and write definition file

Using the name and scanned context, infer a complete skill specification. Do not ask further questions.

Write the inferred specification to .smaqit/definitions/skills/[name].md. Create the directory if it does not exist.

For any field where the correct value is genuinely ambiguous, suffix the value with [?] and add a brief inline note.

The definition file must cover:

• Name and description
• Steps (what the skill does, in sequence)
• Output (what the skill produces)
• Scope (what is out of scope)
• Completion criteria (testable, checkbox-style)
• Failure handling (likely failure modes and responses)
• Gotchas — environment-specific facts the agent must know before executing; non-obvious corrections to mistakes it would make without being told. Distinct from failure handling (which is reactive). Include any project conventions, unexpected API behaviors, naming quirks, or platform constraints that apply to this skill.
• Examples — at least one concrete example of what triggers the skill and what it produces. Input: a representative user request. Output: the artifact or response produced.
• Allowed tools (optional) — if the skill requires specific tools to run (e.g., git, bash scripts), list them as allowed-tools values using the format Bash(git:*), Read, etc.
• Compatibility (optional) — if the skill has environment requirements (specific agent product, system packages, network access), note them here.

4. Compile

Invoke smaqit.L2 as a subagent with:

"Compile the skill definition at .smaqit/definitions/skills/[name].md. Write the compiled skill to .github/skills/[name]/SKILL.md. After compilation, list any fields annotated with [?] and suggest a resolution for each. If the compiled skill body would exceed 400 lines, move detailed reference content to a references/ subdirectory and link from SKILL.md with explicit load conditions ("Read references/[file].md if [condition]"). The main SKILL.md body must remain under 400 lines after extraction."

5. Validate

Read scripts/validate-skill.go before running this step.

Run the validation script against the compiled skill:

go run .github/skills/smaqit.create-skill/scripts/validate-skill.go .github/skills/[name]/SKILL.md

If violations are reported:

1. Surface the violations to the user.
2. Automatically analyse each violation and apply the minimal fix to the definition file (.smaqit/definitions/skills/[name].md) that resolves it — do not ask the user to fix them manually.
3. Re-run Step 4 (Compile) to regenerate the compiled skill from the updated definition.
4. Re-run the validation script.
5. Repeat steps 2–4 up to 3 times in total. If violations still remain after the third attempt, stop, surface the remaining violations to the user, and ask them to update the definition file before re-invoking the skill.

Do not proceed to Step 6 while violations remain.

6. Report

After L2 completes, report to the user:

• Path of the compiled skill file
• Any [?]-annotated items and L2's suggested resolutions
• How to adjust: edit .smaqit/definitions/skills/[name].md and re-invoke /smaqit.create-skill, or switch to smaqit.L2 directly

Output

• .smaqit/definitions/skills/[name].md — inferred specification (scaffolding)
• .github/skills/[name]/SKILL.md — compiled skill file (source of truth)

Scope

Does not create agents, framework files, or templates.

Completion

• Name obtained from user
• Repository scanned for context
• Definition file written to .smaqit/definitions/skills/[name].md
• smaqit.L2 invoked and compilation completed
• Compiled skill exists at .github/skills/[name]/SKILL.md
• Validation script passes with no violations

Failure Handling

Situation	Action
Name not provided	Request before proceeding
.smaqit/templates/ not present	Inform the user that ADK templates are required — run smaqit-adk lite in this repository first
Output artifact already exists	Report the conflict; do not overwrite without user confirmation
L2 invocation fails	Report the error and include the path to the definition file so the user can inspect or correct it
Validation script reports violations	Surface violations to the user; auto-fix the definition file and re-run Steps 4–5 up to 3 times; if violations persist after 3 attempts, ask the user to update the definition file before re-invoking