Creating Rakenne Skills with the Skill Workshop

Rakenne skills are document-elaboration workflows that the agent can run when users describe a task. The Skill Workshop is a dedicated project type that lets you create and publish your own skills through conversation with the agent — no code required. This tutorial walks you through the full workflow: from creating a workshop project to publishing a skill to your organization’s library.

What you’ll need

• Access to a Rakenne instance where you can create projects.
• A clear idea of a domain workflow you want to turn into a skill (e.g. “draft meeting notes from transcripts”, “review contracts against our playbook”, “build a compliance checklist from regulation X”).

Step 1: Create a Skill Workshop project

1. In Rakenne, start Create project (or equivalent in your UI).
2. When choosing a project type, select Skill Workshop.
3. Give the project a name (e.g. “My skill authoring”) and create it.

The workspace is provisioned with:

• Skill-creator skill — A built-in skill at .pi/skills/skill-creator/ that guides the authoring workflow.
• AGENTS.md — Instructions that tell the agent this is a skill authoring workspace and that skills go in output/.
• output/ — An empty directory where every skill you author will live (one subdirectory per skill).

You use the same workspace you already know: chat with the agent, browse the file tree, and preview documents. The only difference is the template and the goal: producing skills instead of a single document.

Step 2: Start the authoring conversation

Open the project and, in chat, say what you want to build. For example:

• “I want to create a skill that turns meeting transcripts into structured notes with decisions and action items.”
• “We need a skill that helps draft privacy impact assessments using our internal template and PIPEDA.”

The agent will use the skill-creator skill and will not create any files until it has understood your workflow. It will ask you questions in a structured way (this is the Elicit phase).

Step 3: Answer the elicitation questions

The agent will ask about:

1. What the workflow is for — Domain and task (e.g. meeting notes, contract review, compliance).
2. What triggers it — When someone would use this skill (e.g. “when the user has a transcript and wants structured notes”).
3. What steps are involved — The sequence (e.g. receive input → extract decisions and actions → confirm ambiguities → produce document).
4. What the output looks like — Document type, sections, format (e.g. executive summary, decision log, action items).
5. Domain knowledge — Regulations, standards, templates, or reference material the agent should use.
6. Other skills it builds on — Whether this workflow relies on or extends another skill already in the library (e.g. “it uses the Create Professional Documents skill for formatting”).

Answer in plain language. If your skill depends on another, say so (e.g. “this skill should run after the user has run the report-templates skill” or “it builds on Create Professional Documents”). The agent will record that as a dependency in metadata so the library can install both when someone adds your skill to a project. The agent will turn your answers into a structured skill; you don’t need to know markdown or YAML. If you have templates or reference docs, you can add them later or describe them so the agent can reference placeholders.

Step 4: Let the agent scaffold and write the skill

Once the agent has enough information, it will:

1. Choose a slug — A kebab-case identifier (e.g. meeting-notes, contract-review-playbook).
2. Call scaffold_skill — This creates output/{slug}/ with a SKILL.md template and optionally references/ and assets/ directories.
3. Edit SKILL.md — It fills in the workflow steps, links to reference files, and adds trigger language to the description so the agent knows when to use this skill.
4. Add reference and asset files — Domain knowledge goes in references/; output templates or examples go in assets/.

All of this happens in the chat; you can watch the file tree and open files to review. Skills are only written under output/.

Step 5: Validate and refine

Before considering the skill ready, the agent will run validate_skill. This checks:

• SKILL.md exists and has valid YAML frontmatter (name, description).
• Description quality — The description includes trigger language (e.g. “Use when…”, “Use for…”).
• Body length — SKILL.md body under 500 lines (long content should go in references/).
• Reference integrity — Links in SKILL.md point to files that exist; no broken links.
• metadata.json — Present and valid (or a warning that it’s missing; you’ll add it in the next step).

If something fails, the agent will suggest fixes (e.g. add trigger language, fix a path, move content to a reference file). You can refine in chat and re-validate until all checks pass.

Step 6: Prepare metadata for the library

When you’re happy with the skill content, the agent will prepare for publish:

1. Run preview_metadata — This shows how the skill will appear in the skill library. If metadata.json doesn’t exist, a draft is generated from the SKILL.md frontmatter.
2. Edit metadata.json — Together you’ll set:
   • title — Human-readable name for the library.
   • description — Short summary (can match or shorten the SKILL.md description).
   • tags — Domain-oriented, English common nouns (e.g. “Productivity”, “Meetings”, “Legal”, “Compliance”).
   • examples — Two or three example prompts that users might type to invoke the skill (e.g. “Structure my meeting transcript into actionable notes”).
   • dependencies (optional) — If your skill builds on other skills, tell the agent: “Add dependencies on [skill name or slug].” The agent will add a dependencies array to metadata.json. See Declaring dependencies below.
3. Validate again — A final validate_skill ensures metadata and structure are complete.

After this, the agent will tell you the skill is ready to publish.

Declaring dependencies

If your skill relies on another skill (e.g. a formatting skill or a shared template skill), you can instruct the agent to add it as a dependency. When someone installs your skill on a project, the system will install the dependencies first so everything works together.

How to ask: In chat, during the metadata step (or when you first mention the dependency in Elicit), say something like:

• “This skill depends on Create Professional Documents — add that as a dependency.”
• “Add a dependency on the report-templates skill from our org library.”
• “It should list create-professional-documents and acme-corp:report-templates as dependencies.”

The agent will edit metadata.json and add a dependencies array. Each entry is a reference to one skill:

• System skill — Use the skill’s slug (e.g. "create-professional-documents") or explicitly rakenne:slug.
• Your organization’s skill — Use your org’s public slug (from Settings), a colon, and the skill slug (e.g. "acme-corp:report-templates"). The agent can look up your tenant public slug if needed.

At publish time, the server checks that every dependency exists and is visible to your tenant. If a reference is wrong or points to another org’s skill, publish fails with a clear error. After publishing, the library shows “Depends on” and “Used by” on skill details, and installing your skill will automatically install its dependencies on the project.

Step 7: Publish to your library

1. In the project workspace toolbar, click Publish Skill.
2. A dialog lists the skills in your output/ directory (each folder that contains a SKILL.md). Select the skill you want to publish.
3. Confirm. The frontend calls the publish API; the skill is copied to your organization’s skill library and registered in the catalog.
4. You’ll see a success message (e.g. “Skill published to library”). The skill is now available when installing skills on any project in your tenant. Republishing the same slug updates the existing skill in place.

Anatomy of a Rakenne skill

A minimal skill in output/{slug}/ looks like this:

• SKILL.md — Required. YAML frontmatter with name (slug) and description (including trigger language). Body: workflow steps, rules, and links to references.
• metadata.json — Required for publishing. title, description, tags (array), examples (array of example prompts). Optional: dependencies (array of strings — skill slugs or tenant_slug:skill_slug for same-tenant skills). Used by the library UI and by the server to record dependency edges and install dependencies when the skill is added to a project.
• references/ — Optional. Markdown (or other) files with domain knowledge; linked from SKILL.md so the agent can read them during the workflow.
• assets/ — Optional. Templates or static assets the agent uses when producing output (e.g. meeting_notes_template.md).

The skill-creator workflow keeps SKILL.md concise and moves detailed content into references/ so the agent gets a clear, scannable workflow plus rich context when needed.

Tips

• One workflow per skill — If you have several distinct workflows, create one skill per workflow; you can author multiple skills in the same workshop project (each in its own output/{slug}/).
• Trigger language matters — The agent uses the skill’s description to decide when to activate it. Phrases like “Use when the user wants to…”, “Use for drafting…”, or “Use to generate…” help the agent match user intent.
• Tell the agent about dependencies — If your skill builds on another (system or your org’s), say so in the Elicit phase or when preparing metadata. For example: “Add a dependency on create-professional-documents” or “This skill depends on our report-templates skill.” The agent will add the correct dependencies entries to metadata.json so the library and install flow work correctly.
• Iterate in the workshop — You can reopen the project anytime, edit files or chat with the agent to change the skill, re-validate, and Publish Skill again to update the library copy.
• No extension.ts for domain skills — The Skill Workshop is for markdown-based skills (SKILL.md + references + assets). TypeScript extensions are out of scope for the guided workflow; the skill-creator does not create or edit extension.ts.

Next steps

• Use Session Management and Context Hygiene so each authoring task stays in a focused session.
• Read Rakenne 0.2.0 — Skill Workshop and More for the full feature set and skill library improvements.
• After publishing, install your skill on a document-elaboration project and run a few example prompts to confirm it behaves as you expect.