lploc94 / create-skill

Create a Raw skill

Use when creating or improving reusable instructions that a Raw agent should discover and load. An ordinary Markdown document does not need skill registration; a new callable action belongs in create_tool.

For a how-to, explain the format, authoring approach and registration with examples. For a requested creation, use the workflow below. For a load failure, inspect the selected ID, frontmatter, body size and error before rewriting instructions.

Read references/packages.md for sharing and references/dashboard.md for browser authoring with read_file.

Establish the useful task

1. Identify the repeated task, expected deliverable, available inputs and tools. Use real examples or corrections from the conversation. Ask only for missing information that changes the result.
2. Choose one coherent responsibility. Describe its boundaries against neighboring skills; avoid both a vague catch-all and many tiny skills needed for a single task.
3. Write the description first: what the user wants, when to use this skill, and a meaningful nearby case that does not need it. The model sees this description in list_skills before seeing the body. Describe intent, not just filenames.
4. Write the body and description in English. Spend words on project-specific facts, decisions, working procedures and common errors. Avoid padding and generic explanations.

Build the instructions

Use these parts where useful; combine short sections rather than filling a rigid form:

• Purpose/routing: intended outcome; explanation, action and diagnosis paths if relevant. Put conditions before action steps.
• Inputs: information to obtain, defaults, paths and actual tool/dependency availability. Reuse supplied answers and authorization.
• Procedure: a default sequence with decisions at the point they matter. Make fragile steps precise; allow judgment for flexible work.
• Contract/example: exact formats, supported fields and realistic example. Label complete files versus fragments and their insertion points.
• Verification/recovery: observable success, important boundary cases and what to do with a specific failure. Distinguish checks performed from assumptions.
• Output: what artifact or answer to deliver and what remaining uncertainty to report.

Keep instructions task-specific: a release-notes skill should not inherit Raw configuration-edit steps. Avoid assumed checkout paths or mandatory external documentation for core behavior.

Raw skill contract

Each skill folder contains UTF-8 SKILL.md with YAML frontmatter. Required name and description are the only catalog authority. Optional scripts/, references/ and assets/ stay with the folder; their contents are not loaded automatically. load_skill returns the whole Markdown body after frontmatter in one linked result, independent of the agent's max_output_bytes; a body over 1 MiB is skipped. Keep it focused: every byte enters the model's context.

--config changes the config-adjacent root, not the global root. Portable folder/name values use lowercase kebab-case, at most 64 characters, no leading/trailing or consecutive hyphens; the frontmatter name matches the folder. Description is nonempty and at most 1024 characters. Selected IDs and names must be unique. Duplicate YAML keys, invalid UTF-8, missing selected files, symlink escapes or oversized bodies fail before inference; unselected folders are inert. Built-in IDs retain their existing underscores through Raw's explicit mapping.

Worked example: release notes

For /work/helper/raw.json, create skills/release-notes/SKILL.md beside it:

<!-- example:body -->

---
name: release-notes
description: Use when drafting a changelog or release summary from a Git comparison range. Group user-visible changes and cite commits; ordinary code review does not need this skill.
---
# Draft release notes

Produce release notes from committed changes. A request to explain the process
needs guidance only; a request for a draft uses the workflow below.

## Inputs
Use the supplied version and Git comparison range. If absent, inspect existing
release tags and changelog conventions; ask only when the intended range remains
ambiguous. Do not invent a version or include uncommitted changes silently.

## Workflow
1. Read the existing changelog format and commits in the chosen range.
2. Inspect changed behavior where commit subjects are insufficient. Group items
   as Added, Changed, Fixed and Removed, or use the project's established format.
3. Include user-visible effects and breaking changes. Omit test-only/internal
   refactors unless they alter behavior. Cite a commit hash or PR for each item.
4. Draft the requested artifact; keep existing release entries intact. Publish
   only when the user has authorized publishing, not merely drafting.

## Check and deliver
Verify cited hashes belong to the comparison range and claims match their diffs.
Run existing Markdown checks when available. If the range is empty, report that
fact; if a change is ambiguous, identify it rather than inventing an effect.
Return the draft, comparison range and any unverifiable or omitted changes.

The following fragment belongs inside agents.helper. Append missing IDs to existing arrays without replacing their contents or order:

<!-- example:registration -->

{
  "tools": { "use": ["builtin/read_file", "builtin/write_file", "builtin/edit_file", "builtin/bash", "builtin/list_skills", "builtin/load_skill"] },
  "skills": { "use": ["agent/release-notes"] }
}

Nonempty skills.use requires both skill tools. Do not change default_agent just to register a skill. If the agent does not exist, use create_agent; otherwise preserve its other fields. For global files, select local/release-notes instead.

Create, verify and improve

1. Establish the actual config/agent and chosen root. Check existing selected names, create SKILL.md and any supporting files, and make the smallest registration edit with a backup of existing config. Keep config mode 0600.
2. Run raw --config /work/helper/raw.json config list (or raw config list for canonical config). This checks config, not skill files.
3. Verify loading without another model call when the @tlelabs/raw library is available: loadConfig({configPath, requireModel:false}), then loadSelectedSkills({selectedIds: runtime.skillIds, configPath}). Or use the configured agent's list_skills and load_skill({name:"release-notes"}) in a suitable run. Confirm the selected name and body, not just a successful config parse.
4. Assess content using a normal task, a boundary case and a near miss. For the example: draft from a known range with verifiable citations; handle an empty range; do ordinary code review without treating it as release-note generation. Review outputs and tool traces for incorrect advice or missing steps. Extra model work is diagnostic.
5. Improve instructions around evidenced errors. Compare versions on the same inputs/model when useful; record which version produced the result. A mock list/load test proves wiring, not writing quality, and no model test guarantees every future action.

The first request has no catalog/body; list/load appends them at the tail. A changed selected skill may add a reload notice on resume without rotating the generated key. List/load again. Trim oversized bodies before increasing the cap.

Report paths, registration, checks and prerequisites.

For dynamic data, teach listvars/readvar and freshness checks; select names in agent.vars and the tools in tools.use. Never bake current time or credentials into a skill. Pass use-only references via consuming tools.