Create your own skill

A folder with a SKILL.md. That's all you need.

Minimal skill structure

A skill is a directory with one required file:

my-skill/
└── SKILL.md

That is a working skill. The agent reads SKILL.md when the skill is invoked and follows the instructions inside it. Everything else is optional.

A more complete skill might look like:

my-skill/
├── SKILL.md           # required: instructions + metadata
├── templates/         # optional: file templates the skill references
│   └── report.md
└── bin/               # optional: helper scripts
    └── analyze.sh

SKILL.md format

The file starts with YAML frontmatter for metadata, followed by markdown instructions:

---
name: deploy
description: Deploy to staging and verify health checks
phase: deploy
trigger: /deploy
intensity: false
---

# /deploy

After /ship completes, deploy the current branch to staging.

## Steps

1. Read the ship artifact to get the commit SHA and PR number.
2. Run `bin/deploy-staging.sh` with the commit SHA.
3. Wait for the health check endpoint to return 200.
4. Save results as a deploy artifact.

## On failure

If the health check fails after 3 retries:
- Save the deploy artifact with status "failed"
- Include the last health check response body
- Do NOT roll back automatically — flag for human review

Frontmatter fields

  • name — the skill identifier. Used in config and logs.
  • description — one-line summary shown in /nano-help.
  • phase — if set, registers this skill as a sprint phase. The skill can save and read artifacts, appear in sprint status, and integrate with /conductor.
  • trigger — the slash command that invokes this skill.
  • intensity — set to true if the skill supports --quick/--standard/--thorough modes.

Register as a custom phase

If your skill's frontmatter includes a phase field, it automatically integrates with the sprint pipeline. See the custom phases page for details on ordering and dependencies.

Example domains

Skills are not limited to engineering. Some examples of what teams have built:

  • Marketing— a /changelog skill that reads ship artifacts and generates user-facing release notes in a specific tone.
  • Data— a /validate skill that checks data pipeline outputs against schema definitions and flags drift.
  • Design— a /audit-a11y skill that checks components against WCAG 2.1 AA criteria and generates remediation tasks.
  • Ops— a /incident skill that reads monitoring alerts and creates a structured incident report with timeline and impact assessment.

Composing with core skills

Custom skills can reference core skills in their instructions. The agent treats them as sequential steps:

---
name: full-deploy
description: Ship, deploy, and verify
trigger: /full-deploy
---

# /full-deploy

1. Run /ship to commit and open a PR.
2. Run /deploy to push to staging.
3. Run /qa --quick against the staging URL.
4. If QA passes, comment "Ready for production" on the PR.

This works because skills are instructions, not code. The agent reads them in order and follows them. Composing skills is just writing a sequence of instructions.

Where to put custom skills

Place the skill directory in ~/.nanostack/custom/ for user-wide availability, or in .nanostack/custom/ at the project root for project-specific skills. Project skills take precedence if there is a name conflict.

Previous← Stack defaultsNextCustom phases →