| name | skill-crafting |
| description | Build a discoverable, reusable capability from a document (/extract-stack) or from deep web research (/craft-stack). Covers when to produce a Skill (agent procedure) versus a Tool (callable shell command), the SKILL.md format, and the write path under the agent-home skills dir. |
| stack | meta |
Skill Crafting
Porcupine can turn a document or a research topic into a real, discoverable capability that auto-injects into context. Two commands drive this:
/extract-stack <path> [--name <n>] [--stack <s>] [--tool] - distill an existing document./craft-stack <name> --desc <description> [--stack <s>] [--tool] - deep-research, then build.
When to Use
- Extract when the source material already exists: a runbook, a paper (PDF), an article, or a spec you want as a reusable procedure.
- Craft when you want a capability that is not yet written anywhere you have, and live research would improve it.
Auto-Use (do not wait to be asked)
This skill is the DEFAULT path for capability creation — invoke it yourself when:
- A document with a repeatable procedure enters your context: the user shares a runbook, paper, spec, article, or a notable log/report that describes steps the agent should follow again — extract it proactively (after confirming the document is worth keeping; do not extract one-off chatter).
- A tool or command fails with a reproducible pattern: you hit the same error twice with a clear recovery path — craft a recovery skill so the next session skips the pain (complements the self-improvement loop's automatic learning; use extract/craft when the failure deserves a hand-written, documented skill).
- A research task produced a reusable procedure: your deep-research or debugging session distilled steps that would help future sessions — craft it while the knowledge is fresh.
- The user asks to "remember how to X" or "make this a skill" — that is an explicit extract/craft request.
When auto-triggered, follow the Procedure below; keep the skill lean (one real procedure, not a dump) and verify discoverability before finishing.
- Skill vs Tool:
- Produce a Skill (a SKILL.md) when the outcome is guidance the agent follows - a procedure, checklist, or reference. This is the default.
- Produce a Tool (a callable shell entry in
user-tools.json) when the outcome is a command the agent should run, e.g. a runbook of terminal steps. Auto-detected for command-heavy documents; override with --tool/--skill.
Procedure
- Decide the kind. Command/runbook-oriented, description reads "run/execute/command" -> Tool. Otherwise -> Skill.
- Read the source. For extract, read the document text (.md/.txt natively, .pdf via
pdftotext). For craft, gather 3-6 source notes (title, url, key points) from web search + extraction.
- Choose a stack id (lowercase a-z, 0-9, hyphens):
web, shell, coding, meta, vcs, docs, data, sci, build, debug, discovery, filesystem, reasoning, safety, etc. When unsure, use meta.
- Choose a name (lowercase a-z, 0-9, hyphens; no leading/trailing/double hyphens).
- Write the SKILL.md to
agentDir/skills/<stack>/<name>/SKILL.md with frontmatter name/description/stack and body sections # Title, ## When to Use, ## Procedure, ## Pitfalls. For a Tool, write a record to <agentDir>/user-tools.json.
- Verify it is discoverable. The next session loads it automatically into
<available_skills>; a direct Skill can also be invoked via /skill:<name>.
Pitfalls
- Never overwrite a user skill without an explicit force flag; refuse with a clear error.
- Never invent URLs, citations, search hits, or facts during research. Cite only sources you actually extracted.
- Keep names/stacks lowercase-hyphen only, or the skill will not validate/discover.
- A distilled Tool needs a real captured command, not just a placeholder echo, to be genuinely callable.
- Truncate oversized documents before distillation; do not blow up context.
Verification
- The SKILL.md parses (has
name/description/stack frontmatter and non-empty description).
- The file sits under
agentDir/skills/<stack>/<name>/SKILL.md for skills, or in user-tools.json for tools.
- The capability is discoverable: it shows in
/stacks and is listed in <available_skills>.
