Create your own skill

A folder with a SKILL.md. Five minutes to build. Composes with every nanostack feature automatically.

1. Create the directory

mkdir -p skills/deploy

The directory name becomes the command name. Users will type /deploy to invoke it.

2. Write the SKILL.md

This is the entire skill definition. YAML frontmatter declares metadata. The markdown body is the prompt the agent follows.

---
name: deploy
description: Deploy the current build to production
concurrency: exclusive
depends_on:
  - ship
hooks:
  - type: PreToolUse
    matcher: Bash
    command: bin/check-dangerous.sh
---

# /deploy -- Ship to production

## Context

Read the most recent /ship artifact to confirm the build passed review,
QA, and security checks. If any phase failed or was skipped, stop and
report what is missing.

## Process

1. Find the ship artifact:
   ```bash
   bin/find-artifact.sh --phase ship --project $(basename $(pwd))
   ```

2. Verify the build hash matches what was reviewed.

3. Run the deployment:
   ```bash
   ./scripts/deploy.sh --env production --hash $BUILD_HASH
   ```

4. Check endpoint health:
   ```bash
   curl -sf https://api.example.com/health | jq '.status'
   ```

5. If healthy, save the deployment artifact:
   ```bash
   bin/save-artifact.sh deploy deploy-result.json
   ```

6. If unhealthy, run rollback and save a failure artifact with the
   error details.

## Artifact schema

```json
{
  "phase": "deploy",
  "environment": "production",
  "build_hash": "abc123",
  "endpoint": "https://api.example.com",
  "health_check": "passed",
  "rollback": false
}
```

3. Register the phase

Add your new phase to .nanostack/config.json so the artifact pipeline recognizes it:

{
  "custom_phases": ["deploy"],
  "phase_order": ["think", "nano", "review", "qa", "security", "ship", "deploy"]
}

4. Install the skill

For Claude Code, symlink the skill directory into your project's .claude/commands/:

ln -s $(pwd)/skills/deploy/SKILL.md .claude/commands/deploy.md

For Cursor, copy the SKILL.md content into a .cursorrulesfile or reference it in your workspace rules. For Codex and other agents, follow their custom instructions mechanism — the SKILL.md is plain markdown, so it works anywhere the agent can read text.

5. Test it

# In Claude Code:
/deploy

# The agent will:
# 1. Read the SKILL.md
# 2. Follow the Process steps
# 3. Run the hooks before any Bash command
# 4. Save the artifact when done

What you get for free

By creating a SKILL.md and registering the phase, your skill automatically inherits the full nanostack pipeline:

  • save-artifact.sh validates JSON structure, adds timestamps, computes integrity hashes, and scans for leaked secrets before writing to disk.
  • find-artifact.shlocates artifacts by phase, project, and recency. Your skill's artifacts are searchable immediately.
  • discard-sprint.shcleans up your phase's artifacts along with everything else when a sprint is discarded.
  • sprint-journal.sh includes your phase in the sprint timeline, with timestamps and durations.
  • The analytics pipeline tracks your phase's usage, duration, and artifact sizes over time.
  • /compoundreads your phase's artifacts and documents learnings alongside the rest of the sprint.
  • /conductorrespects your phase's concurrency and depends_on fields for parallel orchestration.
Previous← HooksNextCustom phases →