Guide

Extending nanostack

Create custom skills for any domain. A skill is a folder with a SKILL.md file. No build step, no SDK, no compilation.

Create your first skill

Step 1: Create the folder

bash

mkdir -p ~/.claude/skills/my-skill

Replace my-skill with your skill name. Lowercase, hyphens for spaces.

Step 2: Write SKILL.md

Create ~/.claude/skills/my-skill/SKILL.md:

markdown

---
name: my-skill
description: One line explaining what this skill does
---

# My Skill

You are a [role]. Your job is to [what you do].

## When to use this skill
Use this when [trigger condition].

## Steps
1. [First thing you do]
2. [Second thing you do]
3. [Third thing you do]

## Output
[What you produce: a file, a report, a decision]

## Next Step
Run /review to verify the output.

The frontmatter (name and description) is required. Everything else is instructions for the AI agent.

Step 3: Use it

/my-skill

The agent reads your SKILL.md and follows the instructions.

Real example: deploy-check

markdown

---
name: deploy-check
description: Pre-deployment checklist before pushing to production
---

# Deploy Check

You are a release engineer. Before any deployment, verify these items.

## Steps
1. Run the test suite. If any test fails, stop.
2. Check for uncommitted changes. If dirty, stop.
3. Verify the branch is up to date with main.
4. Look for hardcoded secrets (API keys, passwords, tokens).
5. Check that environment variables are documented.

## Output
Print a summary:
- Tests: pass/fail (count)
- Branch: clean/dirty
- Secrets: found/clean
- Verdict: READY or BLOCKED (with reason)

## Next Step
If READY, run /ship to create the PR.

Anatomy of a skill

Minimum structure

my-skill/
└── SKILL.md          ← the only required file

Full structure

my-skill/
├── SKILL.md           ← agent instructions (required)
├── references/        ← domain knowledge the agent reads
│   ├── methodology.md
│   └── examples.json
├── templates/         ← output templates
│   └── report.md
└── agents/            ← agent-specific overrides (rare)
    └── openai.yaml

SKILL.md sections

Section	Purpose
Frontmatter	name and description (required). How you invoke the skill.
Role statement	Who am I and what's my job.
Context	What I should read before starting.
Steps	The actions I take, in order.
Output	What I produce when done.
Next Step	What comes after me in the workflow.

Artifacts and cross-skill communication

Skills communicate via JSON artifacts stored in .nanostack/.

Save (at the end of your skill)

bash

bin/save-artifact.sh my-skill '{"phase":"my-skill","summary":{"status":"done","items":5}}'

Read (at the start of the next skill)

bash

bin/find-artifact.sh previous-skill

Returns the most recent artifact for that phase (default: 30-day window).

Register custom phases

Add your skill to the sprint workflow via .nanostack/config.json:

json

{
  "schema_version": "1",
  "project": "my-project",
  "custom_phases": ["my-skill"]
}

Your phase now composes with the core skills. /ship will see it and suggest running it before creating the PR.

Build a complete custom stack

A custom stack is a set of skills that form a workflow for any domain.

Example: Security assessment

/scope-reviewReviews engagement scope, confirms targets, checks authorization/reconMaps attack surface, identifies entry points, documents technologies/findingsTests each entry point, documents vulnerabilities with evidence/reportGenerates client-facing report with executive summary and technical details/deliverCreates deliverable package, checksums, sends via secure channel

Example: Content pipeline

/researchAnalyzes topic, checks competitors, identifies unique angle/draftWrites the piece following brand voice guidelines/review-contentChecks tone, facts, SEO, readability/distributeAdapts to each channel (LinkedIn, Twitter, blog), schedules posts/measureAfter 48h, pulls engagement data, identifies what worked

Mix with core skills

/think → /scope-review → /recon → /findings → /review → /report → /ship

Configurable stack defaults

Override any default tool per project or globally. Three levels of precedence:

Project.nanostack/stack.json: overrides for this repo onlyUser~/.nanostack/stack.json: your global preferencesDefaultsBuilt-in stack-defaults.md: ships with nanostack

Auto-detect your existing stack:

bash

bin/init-stack.sh

Reads package.json, go.mod, or requirements.txt and creates the stack.json. Only configure what you want to change.

Writing tips

Do	Don't
"Look for API keys matching `sk_live_`, `AKIA`"	"Check for security issues"
"Stop if any test fails"	"Tests should pass"
"Output a markdown table with columns: finding, severity, file"	"Report what you find"
"Read `references/checklist.md` first"	"Follow best practices"

The more specific your instructions, the better the agent performs. Write SKILL.md like you're briefing a smart engineer who has access to your entire codebase.