markdown

NAME

markdown — working with Markdown in SLICC: skills, memory, wiki, conversion, and documentation

DESCRIPTION

Markdown is the primary authoring format in SLICC. It is used for skill definitions, agent memory, personal knowledge bases, man pages, and general documentation. The agent reads and writes Markdown natively in chat messages, and several shell commands operate on Markdown files or produce Markdown output. This page collects all Markdown-related capabilities in one place.

SKILLS

Every skill in SLICC is defined by a SKILL.md file — a Markdown document with YAML frontmatter. Skills live at /workspace/skills/<name>/SKILL.md and are the primary extension mechanism for agent capabilities.

Format

---
name: my-skill
description: Teaches the agent how to do X
allowed-tools: bash
---

# My Skill

Instructions for the agent go here in markdown.
Include examples, constraints, and step-by-step workflows.

The YAML frontmatter declares metadata (name, description, allowed tools). The Markdown body contains the full instructions the agent follows when using the skill. Only the description line appears in the system prompt — the body is loaded on demand to conserve context window space.

Reading Skills

skill read <name>          # Print full SKILL.md content
skill list                  # List all discoverable skills
skill info <name>          # Show metadata about a skill

The agent reads a skill's SKILL.md via read_file when it needs to use that skill. Skills are discovered from /workspace/skills/ (native), plus any .agents/skills/ or .claude/skills/ directories in the VFS.

See man skill for full details on skill authoring, installation, and discovery.

MEMORY

Agent memory in SLICC is stored in CLAUDE.md files — plain Markdown documents that are injected into the system prompt. There are three tiers:

/shared/CLAUDE.md — Global Memory

Shared across the cone and all scoops. Contains user preferences, project conventions, and facts every agent should know. The cone updates this file via the update_global_memory tool. Scoops can read it but cannot write to it.

/workspace/CLAUDE.md — Cone Memory

Private to the cone (the orchestrator agent). Use for cone-specific context, workflow notes, or information that scoops don't need.

/scoops/<name>/CLAUDE.md — Scoop Memory

Each scoop has its own memory file. It is loaded into that scoop's system prompt and persists across multiple feed_scoop calls. Use it for scoop-specific instructions, learned context, or running notes.

All memory files use standard Markdown — headings, lists, code blocks, and prose. Keep them concise; they consume system prompt tokens on every turn.

See man memory for persistence, compaction, and best practices.

WIKI

The wiki command provides a personal knowledge base stored as interlinked Markdown files at /mnt/kb. Pages are organized by category and connected with wikilinks.

Commands

wiki search <term>         Search pages by title and content (max 20 results)
wiki list [category]       List all pages, optionally filtered by category
wiki read <note>           Display a page (accepts name, name.md, or category/name)
wiki stats                 Pages per category, file count, date range, wikilink count
wiki links <note>          Show inbound and outbound wikilinks for a page
wiki orphans               Find pages with zero inbound links
wiki recent [n]            Show N most recent source files (default 10)
wiki log [n]               Show last N log.md entries (default 10)

Wikilinks

Pages link to each other using [[Page Name]] syntax. The wiki links command shows both inbound and outbound connections. Use wiki orphans to find unlinked pages that may need integration.

CONVERSION

html-to-markdown

Converts HTML to Markdown using the turndown library. Reads from a file argument or standard input. Commonly used to convert scraped web pages into readable Markdown for the agent to process.

# Convert a web page to markdown
curl -s https://example.com | html-to-markdown

# Convert a local HTML file
html-to-markdown page.html

# Save conversion output
curl -s https://example.com/docs | html-to-markdown > docs.md

Options

-b, --bullet=CHAR          Bullet character for unordered lists (-, +, or *)
-c, --code=FENCE           Fence style for code blocks (``` or ~~~)
-r, --hr=STRING            String for horizontal rules (default: ---)
    --heading-style=STYLE  atx (# headings, default) or setext (underlined h1/h2)

Markdown in Chat

The agent writes Markdown naturally in chat messages — headings, bold, code blocks, lists, and links are all rendered in the conversation UI. No special invocation is needed; Markdown is the default output format.

MAN PAGES

Man pages in SLICC are authored as HTML files (stored on sliccy.com and mounted at /mnt/man/) but are displayed as plain-text Markdown-like content when accessed via the man command. The HTML structure uses semantic elements (h1–h3, p, pre, ul, code) that map cleanly to Markdown conventions.

man <topic>                # Fetch and display a man page
man skill                  # Skill system documentation
man memory                 # Memory and persistence
man delegation             # Scoop delegation patterns

EXAMPLES

Write a new skill

mkdir -p /workspace/skills/my-tool
cat > /workspace/skills/my-tool/SKILL.md <<'EOF'
---
name: my-tool
description: Automates repetitive task X
allowed-tools: bash
---

# My Tool

When the user asks to do X, follow these steps:

1. Check prerequisites with `my-tool status`
2. Run the operation with `my-tool run --target=Y`
3. Report results in a summary table
EOF

Update agent memory

# Add a preference to scoop memory
cat >> /scoops/my-scoop/CLAUDE.md <<'EOF'

## Learned Preferences
- User prefers tabs over spaces
- Always include type annotations in Python
EOF

Query the wiki

wiki search "project alpha"
wiki read work/project-alpha
wiki links project-alpha
wiki orphans

Convert a web page for analysis

curl -s https://docs.example.com/api | html-to-markdown | head -100