matilha-init

AI Community

Repo stars 0
Author repo skills-registry

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Use when starting a new project or initializing Matilha in an existing one — scaffolds project-status.md, AGENTS.md, CLAUDE.md/G…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When this fires”, “Preconditions”, “Execution Workflow”, “Rules: Do”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name matilha-init directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When this fires / Preconditions / Execution Workflow” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

When this fires

User is at the start of a project (no project-status.md) or wants to bootstrap Matilha into an existing codebase. The skill scaffolds the minimum artifacts for Matilha to work: project-status.md with initial phase 0 state, CLAUDE.md / AGENTS.md / GEMINI.md as context primers, and the directory scaffold (docs/matilha/, docs/superpowers/).

Preconditions

Write access to cwd.
No existing project-status.md unless user explicitly confirms overwrite.

Execution Workflow

Verify preconditions via Bash test -f project-status.md. If present and user didn't say "force", ask the user before overwriting.
Prompt the user for archetype (one of: saas-b2b, saas-b2c, frontend-only, cli, library, ml-service, marketplace).
Compute ISO-UTC timestamp via Bash date -u +%Y-%m-%dT%H:%M:%SZ.
Write project-status.md via Write tool. Frontmatter shape: schema_version: 1, name, archetype, created: <iso>, last_update: <iso>, current_phase: 0, phase_status: not_started, next_action: "Run /matilha-scout to enter Phase 10 discovery.", tools_detected: [], companion_skills: {impeccable: not_installed, shadcn: not_installed, superpowers: not_installed, typeui: not_installed}, active_waves: [], completed_waves: [], feature_artifacts: [], recent_decisions: [], pending_decisions: [], blockers: [], aesthetic_direction: null, design_locked: false.
Write CLAUDE.md / AGENTS.md / GEMINI.md if absent (copy from this repo's templates if available via matilha pull, else from skeletons).
Create directories docs/matilha/plans, docs/matilha/specs, docs/matilha/waves via Bash mkdir -p.
Emit final message: "Initialized Matilha — current_phase: 0. Next: /matilha-scout".

Rules: Do

Respect explicit overwrite confirmation; do not silently clobber.
Use ISO-UTC timestamps throughout.
Create docs/ directories idempotently (skip if they exist).

Rules: Don't

Overwrite existing project-status.md without explicit user confirmation.
Guess archetype from code (ask).
Use local-time timestamps.

Expected Behavior

On success, user has a Matilha-initialized project with the 3 context files + project-status.md. Next skill the user invokes is typically matilha-scout (Phase 10) or matilha-plan (Phase 20-30) if they already have research.

Quality Gates

project-status.md exists with valid frontmatter (conforms to projectStatusSchema).
docs/matilha/ directory tree exists.
Context files (CLAUDE.md / AGENTS.md / GEMINI.md) exist.
User can run matilha-howl next and see phase 0 state.

Companion Integration

No companion integrations in Wave 4a. Future packs may extend this skill.

Output Artifacts

project-status.md
CLAUDE.md (if absent)
AGENTS.md (if absent)
GEMINI.md (if absent)
docs/matilha/plans/
docs/matilha/specs/
docs/matilha/waves/

Example Constraint Language

Use "must" for: project-status.md conforms to projectStatusSchema; ISO-UTC timestamps.
Use "should" for: prompt interactively for archetype; skip overwrite of existing context files.
Use "may" for: scaffold additional directories beyond the required ones if user requests.

Troubleshooting

"project-status.md already exists": User confirms overwrite explicitly, or chooses a different directory.
"archetype not recognized": Must be one of saas-b2b, saas-b2c, frontend-only, cli, library, ml-service, marketplace; ask user to pick from the list.

CLI shortcut (optional)

If matilha CLI is installed (matilha --version succeeds), you can run matilha init to execute this deterministically. The plugin path above works without any CLI installation.

Source: danilods/matilha-skills — distributed by TomeVault.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: AI
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @tomevault-io · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview matilha-init.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

## When this fires

User is at the start of a project (no `project-status.md`) or wants to bootstrap Matilha into an existing codebase. The skill scaffolds the minimum artifacts for Matilha to work: `project-status.md` with initial phase 0 state, `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` as context primers, and the directory scaffold (`docs/matilha/`, `docs/superpowers/`).

## Preconditions

- Write access to cwd.
- No existing `project-status.md` unless user explicitly confirms overwrite.

## Execution Workflow

1. Verify preconditions via Bash `test -f project-status.md`. If present and user didn't say "force", ask the user before overwriting.
2. Prompt the user for `archetype` (one of: `saas-b2b`, `saas-b2c`, `frontend-only`, `cli`, `library`, `ml-service`, `marketplace`).
3. Compute ISO-UTC timestamp via Bash `date -u +%Y-%m-%dT%H:%M:%SZ`.
4. Write `project-status.md` via Write tool. Frontmatter shape: `schema_version: 1`, `name`, `archetype`, `created: <iso>`, `last_update: <iso>`, `current_phase: 0`, `phase_status: not_started`, `next_action: "Run /matilha-scout to enter Phase 10 discovery."`, `tools_detected: []`, `companion_skills: {impeccable: not_installed, shadcn: not_installed, superpowers: not_installed, typeui: not_installed}`, `active_waves: []`, `completed_waves: []`, `feature_artifacts: []`, `recent_decisions: []`, `pending_decisions: []`, `blockers: []`, `aesthetic_direction: null`, `design_locked: false`.
5. Write `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` if absent (copy from this repo's templates if available via `matilha pull`, else from skeletons).
6. Create directories `docs/matilha/plans`, `docs/matilha/specs`, `docs/matilha/waves` via Bash `mkdir -p`.
7. Emit final message: "Initialized Matilha — current_phase: 0. Next: /matilha-scout".

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> When this fires → Preconditions → Execution Workflow → Rules: Do → Rules: Don't → Expected Behavior
terms    -> "project-status.md already exists" · "archetype not recognized" · User is at the start of a project (no project-status.md) or wants to bootstrap Matilha into an existing codebase. · - Write access to cwd. · 1. Verify preconditions via Bash test -f project-status.md. · - Respect explicit overwrite confirmation; do not silently clobber. · - Overwrite existing project-status.md without explicit user confirmation. · On success, user has a Matilha-initialized project with the 3 context files + project-status.md.
files/cmd -> project-status.md · CLAUDE.md · AGENTS.md · GEMINI.md · docs/matilha/ · docs/superpowers/ · test -f project-status.md · archetype
body sha256 -> 08e45be42786