coconut-skills-creator

Coconut Skills Creator

A meta-skill for authoring Coconut skills: single-file SKILL.md documents that run on a Coconut instance — a VM with the nut CLI installed and a .nut/ directory. At runtime the SKILL.md is consumed by Claude Code (or an equivalent agent loop) on that instance, which executes nut subcommands to manipulate tasks, resources, knowledge, context, and third-party connectors.

Your job is to turn a user's description — whether a plain-English goal or a rough step list — into a well-formed SKILL.md that another instance of Claude can read and execute on a Coconut.

What matters is that the generated skill works at runtime — reads the right files, runs the right nut commands, produces the right artifact, and is unambiguous enough that the runtime agent doesn't have to guess. Business-like and efficient is fine. Don't try to preserve anyone's "voice" — optimize for a runtime agent that will read and execute.

What Coconut skills look like

A Coconut skill is fundamentally a prompt with nut commands woven into it. It reads relevant .nut/ files for context, reasons about what to do, takes action by shelling out to nut subcommands, and typically ends by creating a task or notifying a channel. Use direct, instructional language — imperative voice, concrete commands, clear "read first / then do / then report" structure.

Coconut skills are NOT:

• Python packages or bundles with scripts/ and assets/
• Code-generation templates
• Rigid step-by-step scripts with hard-coded branching

They ARE:

• A prompt, opinionated about what to do and which nut commands to use, but trusting the runtime agent to adapt

Keep this distinction top of mind — the output is a single markdown file with YAML frontmatter, nothing else.

Workflow

Step 1: Detect the input mode

The user will give you one of two things:

Mode A — Plain-English goal. A description of what the skill should accomplish, without specifying steps. Example: "create a loop that drafts new tasks for me based on my role and memory, avoiding duplicates, and notifies Slack when done." Your job is to fill in the structure: which .nut/ files to read, what the reasoning should look like, which nut commands to emit, what the "done" signal is.

Mode B — Rough step list. Numbered or bulleted steps, possibly with missing detail. Example: "1. read my role and memory. 2. check for new LinkedIn activity. 3. suggest a post. 4. create a task. 5. tell Slack." Your job is to formalize the steps, wire the right nut commands to each, add the reading-context prelude, and insert missing scaffolding (deduplication checks, done notifications, etc.).

You don't need to ask the user which mode they're in — just read the input and proceed. If it's ambiguous, treat it as Mode A (goal) and let the skeleton fill in more structure.

Step 2: Elicit missing details — only what's actually missing

Do NOT pepper the user with a questionnaire. Look at what they gave you and ask only about gaps that genuinely block drafting. Common gaps:

• External services. If the user's description mentions Linear, Notion, Slack, Amplitude, LinkedIn, Stripe, email, posting to a social platform, "notifying the team," or any other third-party integration — ask which connectors they expect to use (or confirm the ones they named). If their description contains no mention of external services, DO NOT bring up connectors at all.
• Cadence. If the user said "daily loop" or "weekly review" or similar, you have it. Otherwise you don't need to ask — a Coconut skill's SKILL.md doesn't encode its own cadence; the scheduler that invokes it does.
• Completion signal. If the user didn't say how "done" is communicated (Slack? Just create a task? Update a knowledge file?), pick the most obvious option based on the goal and state the assumption in the draft. Only ask if truly ambiguous.

Prefer assume and state the assumption over ask. You can always iterate after the user reviews the draft.

Step 3: Draft the SKILL.md

Follow the skeleton in references/skeleton.md. Key moves:

• YAML frontmatter: name (kebab-case, derived from the goal — e.g., self-task-loop, linkedin-activity-loop), and a description of 1–2 sentences that states what the skill does and when it should trigger. Be specific, not flowery. Under-triggering is the bigger risk than over-triggering, so err toward a slightly pushier description rather than a demure one, but keep it short.
• Reading prelude: start the body with the specific .nut/ files this skill should read. See references/nut-directory.md for canonical paths. At minimum, most skills should read .nut/config.json for identity and .nut/context/role.md for role. Include .nut/context/memory.md and .nut/context/team.md where relevant — these are loose markdown files in .nut/context/ (not documented context types like project/architecture/role, but real files your skills should read).
• Body: the actual instructions. Imperative voice. Concrete nut commands inline. Reference references/nut-cli.md for correct syntax. Don't pad with preamble — get to the work.
• Completion: end with what "done" looks like — usually nut task create … (to capture output) and/or a notification via Slack.

Step 4: Show the user the draft and iterate

Always show the full drafted SKILL.md to the user before considering yourself finished. Ask "does this match what you had in mind?" — not "is this perfect?" — and iterate on their feedback. If the user gives terse feedback ("make it more skeptical" / "add a dedup check"), apply it and re-show.

Reference files

Read these as you draft — don't try to remember CLI syntax from memory, the docs are authoritative and the platform changes:

• references/nut-cli.md — canonical nut command syntax: task, resource, knowledge, context, connect, skill. Pulled from https://docs.coconut.dev.
• references/nut-directory.md — the .nut/ directory layout and what lives where.
• references/skeleton.md — the template a good Coconut skill looks like, with slots to fill in.
• references/examples.md — five concrete example skills (self-task loop, LinkedIn activity, unmet-need brainstorm, market intel, cross-Coconut blog-post creation) to calibrate your sense of shape, depth, and voice.

Connectors and nut connect

If the user's description mentions a third-party service, use nut connect to reach it. Canonical commands:

• nut connect list — shows which connectors are available on this instance. Generated skills can include this as a self-check before using a connector.
• nut connect proxy <app> <method> <path> --body '<json>' — the docs-accurate way to call any connected service.

Your generated skills can also use ergonomic shorthand forms that appear in hand-written Coconut skills:

• nut notify slack "message" — ergonomic Slack notification.
• nut connect coconut call <tool> --args '<json>' — ergonomic cross-Coconut call (for reaching another Coconut instance's tools like tasks_create, context_get, etc.).

Use the shorthand. It matches the voice of hand-written Coconut skills, and the runtime (Claude Code on a Coconut) handles unknown subcommands gracefully — if a shorthand isn't recognized, it'll translate to nut connect proxy on its own. You don't need to scaffold fallbacks into the generated skill.

Style for generated skills

Study the examples in references/examples.md — they are the ground truth for structure (what to read, how to order sections, where closers go). You don't need to imitate their prose. A few things to keep consistent:

• Direct imperative. "Read this. Then do that. Then notify Slack." Not "The skill should consider reading…"
• Concrete paths and commands inline. .nut/knowledge/market.md, nut task create "<title>" -c "<markdown>". Not abstract references like "the market file."
• Fit length to the task. Short skills for simple read-act-report loops. Long skills only when real scaffolding is needed (e.g., multi-step skeptical brainstorms). Don't pad to look more thorough.
• Opinionated where it matters. If the user's goal requires skepticism, constraints, or anti-pattern guardrails, encode them explicitly the way the "Unmet Need Loop" example does.
• No cheerful preamble or meta-commentary. The skill does the work; it doesn't describe itself.

Output

The deliverable is a single SKILL.md file. The user installs it on their Coconut via the Coconut Connector's skill_create/skill_update tools (or equivalent), so you don't need to create a containing directory or bundled resources — just the markdown file with frontmatter.

Show the file inline in the conversation AND (when a filesystem is available) save it to a predictable path so the user can easily copy it.

A note on the meta-skill's own judgment

The user's examples are more important than the docs when they conflict. The docs are authoritative for syntax; the examples are authoritative for structure and what a real Coconut skill looks like on the ground. If the examples use a nut shorthand that isn't in the docs, trust the shorthand — the user maintains both and the docs lag reality.

When in doubt, imitate the examples' structure, then iterate with the user.