moskills
By Mouad Belghiti.
moskills is my small skill pack for working with AI agents without letting the work become random.
It is the fruit of learning from engineers, experts, and successful GitHub repos. I pulled together the patterns that kept showing up: align first, use shared language, map the system, create fast feedback loops, checkpoint progress, validate before done, and leave clean handoffs.
The goal is simple: install one folder into any project, then use clear slash commands when the agent needs structure.
Installed Commands
/align-intent: confirm goals, constraints, success criteria, non-goals, and risks before coding./shared-language: turn project jargon into a glossary agents and humans can share./system-map: map modules, data flow, dependencies, risk areas, and the safest change boundary./tdd: run the red, green, refactor loop for behavior changes./diagnose: debug by reproducing the issue and finding root cause before fixing./checkpoint: record factual progress, Git deltas, blockers, commands run, and next steps./gatekeeper: validate completed work against the active intent model before reporting completion./compress-input: switch to short, direct technical communication./memorize: use durable memory for lessons, rules, and past-session context./handoff: compact current work so another agent can continue.
How the Agent Knows When to Use Skills
1. Automatic (the default)
Each skill is a folder with a SKILL.md file. The top of that file holds a
short description with a Use when: trigger line. For example:
---
name: diagnose
description: "Use when: debugging bugs, failing tests, broken builds, regressions, performance issues, or unexpected behavior."
---
The agent reads these descriptions and matches them against what you are asking
for.
This is why the descriptions matter more than the command names. A precise
Use when: line is what makes the skill discoverable and self-triggering.
2. Manual (the slash command)
Typing the slash command, like /diagnose, forces that skill to run even if the agent did not trigger it on its own.
Install
Option A: Plugin (recommended, one line, updates centrally)
Install moskills as a Claude Code plugin. The skills become available in every
project, and you update them in one place instead of per project.
From inside Claude Code, add the marketplace once, then install:
/plugin marketplace add Mouad1/moskills
/plugin install moskills@moskills
To update later, pull the latest version centrally:
/plugin update moskills@moskills
This installs all skills and their slash commands globally. No files are
copied into your project.
Option B: Copy script (per project, no plugin system)
Run from this repository after cloning or downloading it, to copy the .claude/
folder into one project:
./setupskill.sh --target /path/to/project
./setupskill.sh --target /path/to/project --with-hooks
./setupskill.sh --target /path/to/project --dry-run
./setupskill.sh --target /path/to/project --force
Flags:
--target /path/to/project: install into a specific project directory.--with-hooks: install a Git pre-commit wrapper when the target is a Git repository.--dry-run: print planned writes without changing files.--force: overwrite existing managed files.
What users get
Users get files inside their own project:
.claude/commands/: slash commands they can call directly..claude/skills/: deeper workflows the agent can load when needed..claude/STATE.md: durable context outside the chat window..claude/hooks/agent-guard.sh: optional staged-file guard..git/hooks/pre-commit: installed only with --with-hooks.
What I use in this repo
This repo keeps the source of the pack:
templates/claude/: what gets copied into user projects.setupskill.sh: the installer.tests/run-tests.sh: smoke tests for install behavior and hooks.docs/: usage docs and examples.
Lifecycle
Project Start -> /shared-language
New Feature -> /align-intent -> /system-map -> Coding Phase with /tdd or /diagnose and /checkpoint -> /gatekeeper -> Done
If work must pause, use /handoff.
Hook Flow
Hooks are optional. They run only if installed with --with-hooks.
Git Workflow Rule
Do not push directly to the default branch. Push a branch and open a pull request.
Internal planning files stay local. This repo ignores tasks/ and docs/superpowers/ so private plans, specs, and working notes are not shipped with the public pack.
git commit -> .git/hooks/pre-commit -> .claude/hooks/agent-guard.sh -> allow or block commit
The guard checks staged files. It blocks conflict markers and selected risky placeholder phrases. It also prints simple validation suggestions, like npm test for Node or pytest for Python.
Installed Files
