Guide

Extending nanostack

Add a custom phase that the framework treats as a real phase. Same resolver, journal, analytics, guard, session, and conductor lifecycle as the built-in skills.

Scaffold a skill

Use bin/create-skill.sh from the nanostack repo root. The script writes SKILL.md, agents/openai.yaml, and the directory layout the framework expects.

bash
bin/create-skill.sh license-audit --concurrency read --depends-on build

--concurrency declares whether the phase reads or writes. Read-only phases parallelize and are blocked from writing by guard. --depends-on declares the upstream phase whose artifact this skill needs. The resolver uses it to populate phase_context.

Validate the contract

bin/check-custom-skill.sh validates the skill against the Custom Stack Framework contract: required files, frontmatter shape, concurrency value, depends_on graph, and artifact schema.

bash
bin/check-custom-skill.sh .nanostack/skills/license-audit

The validator runs locally and is the same gate the contract test runs in CI. Treat a passing check as the bar for any custom skill.

Where the skill lives

Skills resolve through the Nanostack store, not a hardcoded host directory. By default the store is .nanostack/skills/ in the project, with $NANOSTACK_STORE as an override. The same resolver is what host adapters use to surface the skill, so you do not symlink into ~/.claude/skills manually.

Anatomy of a skill

.nanostack/skills/license-audit/
├── SKILL.md             # frontmatter + agent instructions (required)
├── agents/
│   └── openai.yaml      # adapter-specific behavior (read by the host)
├── references/          # optional domain knowledge the skill reads
└── artifacts/
    └── license-audit.schema.json  # optional schema for the artifact

The frontmatter declares how the framework treats the skill, not just metadata for the host:

yaml
---
name: license-audit
description: Audit third-party licenses before release.
concurrency: read           # read, write, or exclusive
depends_on:
  - build                   # one or more upstream phases
phase_kind: custom
artifact_schema: artifacts/license-audit.schema.json
---

The body is the agent prompt. Use the resolver at the start, save an artifact at the end:

markdown
# /license-audit

## Context
Run `resolve.sh` to get upstream artifacts, phase_context, routing.trust,
and upstream_status. If `upstream_status` is not "fresh", stop and report.

## Process
1. Read the build artifact and list third-party dependencies.
2. For each dependency, fetch the license.
3. Flag anything outside the allowlist.

## Output
Save the artifact:
```bash
bin/save-artifact.sh license-audit license-audit.json
```

Register the phase

Add the skill to .nanostack/config.json so the resolver, conductor, and guard treat it as a real phase.

json
{
  "custom_phases": ["license-audit"],
  "phase_graph": {
    "license-audit": {
      "depends_on": ["build"],
      "before": ["security"]
    }
  }
}

Use phase_graph when the skill is part of a custom stack with multiple new phases. Use plain custom_phases plus the frontmatter depends_on for one-off skills.

What the skill gets for free

CapabilityWhat you get
save-artifact.shAccepts the custom phase, validates the artifact schema, and adds the SHA-256 integrity field.
find-artifact.shFinds the artifact by phase and integrity, and can require integrity with --require-integrity.
resolve.shReturns phase_kind: "custom", upstream artifacts, past solutions, config, phase_context, routing.trust, and upstream_status.
Sprint journalThe phase appears in timelines and per-phase stats.
AnalyticsUsage, duration, and artifact sizes tracked over time.
ConductorSchedules the phase and reads its concurrency metadata.
Guard concurrencyRead-only custom phases block writes during their run.
Discarddiscard-sprint.sh cleans up the phase's artifacts.

Build a custom stack

A custom stack is a set of skills wired with phase_graph. The worked example is compliance-release, which adds three phases before /ship.

/license-auditReads build artifact, lists third-party deps, flags non-allowlisted licenses./privacy-checkReads build artifact, scans for PII handling and consent boundaries./release-readinessReads license-audit and privacy-check, produces the release decision artifact.

The example ships with 49 static contract checks and a 15-cell, 51-assertion runtime harness in the opt-in E2E workflow. It is an advanced example and a release decision aid, not a compliance certification.

/think → /nano → build → /review → /security → /qa → /license-audit → /privacy-check → /release-readiness → /ship

Writing tips

DoDon't
"Run resolve.sh first and stop if upstream_status is not fresh""Read the previous artifact"
"Look for API keys matching sk_live_*, AKIA*""Check for security issues"
"Save the artifact with bin/save-artifact.sh using the declared schema""Write a JSON file somewhere"
"Stop if any test fails""Tests should pass"
"Output a markdown table with columns: finding, severity, file""Report what you find"

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

Share your skill set

The canonical references for the Custom Stack Framework are in the repo:

← nanostack.sh