mags-init
npx machina-cli add skill doancan/mags/mags-init --openclawMAGS Init
Initialize the Memory And Guidance System for this project.
Steps
1. Check existing state
Check if a docs/ directory already exists in the project root. Also check for .mags/ directory and any existing CLAUDE.md.
Use Glob to scan for docs/**/*.md and check for .mags/config.yaml.
2A. If docs/ exists — Index existing documentation
Report what was found:
- Number of documents in docs/
- List the top-level structure
Call mags_list_docs to see if MAGS already has indexed documents. If not, read each markdown file in docs/ and call mags_create_doc to index them into MAGS.
Tell the user: "Found existing docs/ directory with N documents. Indexed into MAGS."
2B. If docs/ does not exist — Gather project info
Ask the user these questions (all at once, not one by one):
- What is this project? (brief description)
- What is the tech stack?
- What is the current state? (new, in progress, mature)
- What is the architecture type? (monolith, microservices, library, cli, mobile, serverless)
- What language should documentation be in? (en, tr, or other locale)
Call mags_detect_stack to auto-detect the project's tech stack. Use this information to enrich the docs.
Then create the docs/ directory structure using mags_create_doc with these templates. Pass the user's chosen locale (from question 5) as the locale parameter to each mags_create_doc call:
docs/architecture/overview.md— Project overview from user answersdocs/architecture/tech-stack.md— Tech stack detailsdocs/rules/coding-standards.md— Basic coding standards for the stackdocs/changelog/changes.md— Empty changelog
Stop here and wait for user answers before creating docs.
3. Create .mags/ directory
Create the following structure:
.mags/
config.yaml — MAGS configuration
config.yaml content:
version: 1
project_root: .
docs_path: docs/
locale: <user's chosen locale from question 5, e.g. "en" or "tr">
initialized_at: <current ISO date>
Use the locale code the user selected in question 5 (en, tr, etc.) as the locale value.
4. Offer CLAUDE.md generation
Ask the user: "Would you like me to generate a CLAUDE.md file based on your project docs?"
If yes, call mags_generate_claude_md and write the result to the project root.
5. Save initial memory
Call mags_remember with:
- key:
project_initialized - value: Brief description of what was set up (e.g., "Project X initialized with N docs, tech stack: ...")
- category:
context - tags:
["init"]
This ensures the memory system has at least one entry from the start.
6. Summary
Print a summary:
MAGS initialized successfully.
Project: <name>
Docs: <N> documents indexed
CLAUDE.md: <generated / skipped>
Next steps:
→ /mags-help — See all available commands
→ /mags-status — View project dashboard
→ /mags-setup — Get Claude Code configuration recommendations
Overview
Initializes the Memory And Guidance System (MAGS) for the current project. It checks for an existing docs/ directory and .mags folder, indexes docs into MAGS when present, or gathers project details to scaffold documentation and configuration. It can also generate CLAUDE.md and saves an initial memory entry for project context.
How This Skill Works
The skill uses Glob to detect docs/**/*.md and checks for .mags/config.yaml. If docs exist, it calls mags_list_docs to review indexed content and mags_create_doc to index each Markdown file. If docs are absent, it invokes mags_detect_stack to infer the tech stack, prompts for project details to populate templates, and then creates the docs structure and .mags/config.yaml with the chosen locale before optionally generating CLAUDE.md.
When to Use It
- The repository already has a docs/ directory and you want to index or re-index documents into MAGS.
- No docs/ directory exists and you want to scaffold a MAGS setup based on your project details.
- You want to initialize MAGS configuration (.mags/config.yaml) with a specified locale.
- You plan to generate a CLAUDE.md based on project docs after initialization.
- You want to save an initial memory entry about the project initialization for context and tracking.
Quick Start
- Step 1: Run mags-init in the project root to begin initialization.
- Step 2: If docs/ exists, allow the tool to index documents using mags_list_docs and mags_create_doc; if not, mags_detect_stack will guide scaffolding.
- Step 3: Review the generated .mags/config.yaml and, if desired, opt into generating CLAUDE.md and save the initial memory with mags_remember.
Best Practices
- Verify the docs/ directory contents before running mags-init to ensure relevant files are indexed.
- Run mags_list_docs after initialization to confirm what was indexed into MAGS.
- Provide an accurate locale (en, tr, etc.) when prompted for language for documentation.
- Review and adjust the generated .mags/config.yaml to reflect the correct project_root and docs_path.
- Document any manual edits to the docs structure to keep MAGS in sync with the repo.
Example Use Cases
- A new library repo with extensive Markdown docs runs mags-init; existing docs are indexed into MAGS and a memory entry is created.
- An app with no docs prompts the user for stack details, then mags-init scaffolds docs/architecture and docs/tech-stack and creates .mags/config.yaml.
- A monorepo uses mags-init to check for docs/, detects a microservices architecture with Node and Python services, and sets locale to en.
- Docs are present but not indexed; mags-init runs mags_list_docs and mags_create_doc to index each Markdown file into MAGS.
- CLAUDE.md generation is enabled after initialization, producing a Claude-style guidance document from the project docs.
