writing-skills

Files (3)

• SKILL.md
• persuasion-principles.md · references/
• testing-skills.md · references/

SKILL.md (first lines)

# Writing Skills

A skill is process code. Write it to change future agent behavior, not to
record a past fix.

## Iron Law

Every new skill or content edit needs a pressure test: baseline behavior fails
without the skill, then treatment behavior complies with the skill. If the text
does not move behavior, tighten the text before promoting it.

Violating the letter is violating the spirit. A vague skill that gets ignored is
worse than no skill because it still spends context.

## Description Rule

The frontmatter `description` says when to use the skill, not what the body
contains. Start with `Use when` or `Use before`.

Bad: `description: Explains the workflow for verifying work.`

Good: `description: Use before claiming work is done, fixed, passing, complete, or ready to merge.`

If the description summarizes the steps, the agent may take it as a shortcut and
skip the body.

## Structure

For discipline skills, prefer this shape:

1. Iron Law: the rule that must survive pressure.
2. Reality check: why violating the letter violates the spirit.
3. Rationalization table: common excuse and the actual requirement.
4. Red Flags: phrases or situations that mean stop and apply the skill.
5. Gate Function: the concrete check before proceeding.

## Rationalization Table

| Excuse | Reality |
| --- | --- |
| "This is obvious." | Obvious rules still need executable steps and a gate. |
| "The description is enough." | The body is where behavior changes. |
| "No eval is needed for wording." | Skill wording is agent-facing control logic. |

## Red Flags

STOP when the skill draft:

- Retells one incident instead of naming a reusable class of work.
- Uses forced file-load links instead of progressive disclosure.
- Hides the trigger in the body instead of the description.
- Says "consider", "try", or "be mindful" without a gate.
- Has no before/after compliance fixture.

## Gate Function

Before creating or promoting a skill:

1. Confirm the name is lowercase, stable, and class-level.
2. Confirm the description is a trigger.
3. Keep the body concise; move deep references to `references/`.
4. Run `aimee skill lint <name>` or lint the proposed content.
5. Run `aimee skill eval <name>` when eval fixtures exist.
6. Promote only when lint passes and eval evidence shows improvement, or record
   the missing evidence explicitly for human review.

## Layout

Keep principles and code patterns inline when they fit. Put heavy background in
`references/`, reusable text in `templates/`, scripts in `scripts/`, and assets
in `assets/`. Cross-reference other skills by skill name, not path.

This skill adapts authoring discipline from the MIT-licensed
`obra/superpowers` project for aimee's local skill engine.

From RakuenSoftware/aimee, AGPL-3.0.

More from RakuenSoftware/aimee