Writing Custom Skills

Create project-specific skills that extend the mbscode framework. Custom skills follow the same format as built-in skills and are loaded via the project's skill manifest.

When to Use

• Adding a project-specific workflow (e.g., deployment, database migrations, i18n)
• Codifying a team practice that should be enforced by the AI
• Overriding a built-in skill with project-specific behavior

Required Structure

Every skill file MUST have:

1. YAML Frontmatter

---
name: skill-name
description: "When to use -- trigger conditions that tell the agent to invoke this skill"
---

The description field is critical -- it determines when the agent activates this skill. Write it as a clear trigger condition, not a vague summary.

Bad Description	Good Description
"Handles deployment"	"Use before deploying to any environment -- covers pre-deploy checks, deploy steps, and rollback"
"Database stuff"	"Use when creating or modifying database migrations -- ensures reversibility and data safety"

2. Title and Purpose

One sentence explaining what this skill does and why it exists.

3. Process or Checklist

Step-by-step procedure. Use numbered lists for sequential steps. Each step must be actionable -- not "consider X" but "do X".

4. Red Flags Table

Rationalization patterns specific to this skill. Format:

## Red Flags

| Thought | Reality |
|---------|---------|
| "This doesn't need migration rollback" | Every migration needs a rollback. No exceptions. |

Optional Sections

• HARD-GATE -- Non-negotiable rules that cannot be skipped
• Scope-Based Scaling -- How to adapt effort to task size
• Transitions -- Which skills come before/after this one
• Examples -- Concrete examples (keep concise -- examples consume tokens)

Registering Custom Skills

Add custom skills to the ## Custom Skills section in PROJECT.md:

## Custom Skills

| Skill | Path | Trigger |
|-------|------|---------|
| `deploy` | `skills/deploy/SKILL.md` | Before any deployment |
| `migrations` | `skills/migrations/SKILL.md` | When creating/modifying DB migrations |

The agent reads this manifest alongside the built-in skill manifest and invokes matching skills.

Overriding Built-in Skills

To replace a built-in skill with a project-specific version:

1. Create a custom skill with the same name as the built-in skill
2. Register it in PROJECT.md's Custom Skills section
3. The project-local version takes precedence over the built-in version

Example: To replace autonomous-review with a simpler version for a small project:

| `autonomous-review` | `skills/autonomous-review/SKILL.md` | After completing a milestone |

Quality Criteria

Before committing a custom skill, verify:

• Trigger is specific -- description clearly says WHEN, not just WHAT
• Steps are actionable -- every step starts with a verb
• No vague language -- no "consider", "if appropriate", "as needed" without concrete criteria
• Red flags exist -- at least 3 rationalization patterns specific to this skill
• Token-efficient -- no redundant examples, no filler text, every line earns its place
• Self-contained -- skill can be understood without reading other skills
• Tested -- run a task that triggers this skill and verify the agent follows it correctly

Red Flags

Thought	Reality
"This skill is too simple to need a Red Flags table"	Simple skills get skipped. Red flags prevent that.
"I'll add more detail later"	Write it now. Incomplete skills get ignored.
"The description is fine as-is"	If the trigger isn't specific, the agent won't invoke it.
"One big skill for everything"	Split by concern. One skill = one workflow.