Index of every page on this site: llms.txt
All skills
laude-institute avatar

/skill-author

@8db84fd
Run it yourself

Create new ShellLM skills. Use when the user asks to write, author, build, or scaffold a new skill, or when an agent needs to extend its own capabilities by creating a new SKILL.md file.

  • 1 file
  • 5.1 KB
  • Updated 3 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/laude-institute/headlong/skill-author

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈50 tokens for metadata: the name and description. ≈1.2k when used: this file.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈201 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

skill-author

When to use

The user asks to create, write, author, build, or scaffold a new skill. Or you (the agent) need to extend your own capabilities by writing a new SKILL.md.

What a skill is

A skill is a directory containing a SKILL.md file. It tells an agent when to use a capability and how to invoke it. Skills are procedural documentation, not reference docs. The agent reads a skill on demand via skills show <name>.

Directory structure

skills/<skill-name>/
├── SKILL.md           # required: the skill definition
├── README.md          # optional: human-facing notes
└── <other files>      # optional: scripts, templates, data

Frontmatter spec

---
name: my-skill
description: One or two sentences. Be specific about WHEN to use the skill.
metadata:
  shelllm:
    requires:
      env: ["API_KEY"]           # all must be set
      bins: ["curl", "jq"]      # all must exist on PATH
      anyBins: ["gh", "hub"]    # at least one must exist
      os: ["darwin", "linux"]   # current OS must be in list
---

Required: name (kebab-case, matches directory name), description.

Description matters. It's matched against user intent. Bad: "manages files." Good: "Read, write, search, and append notes in an Obsidian vault. Use when the user mentions Obsidian or asks to interact with markdown notes."

Requirements are optional. Only declare metadata.shelllm if the skill needs env vars, binaries, or a specific OS. Skills with unmet requirements are filtered from skills list.

Writing the body

Write for an agent reader, not a human:

  • Skip marketing language and "why use this"
  • Lead with concrete commands, not prose
  • Use tables for command references when they fit
  • Keep it under 1,000 tokens -- agent context is precious
  • Examples should be copy-pasteable shell commands, not pseudocode
  • Don't enumerate all flags -- teach the patterns specific to this tool

Recommended structure

## When to use
[Concrete intent triggers]

## Setup
[One-time prerequisites: env vars, services to enable]

## Common operations

### Operation 1
\`\`\`bash
exact command here
\`\`\`
One sentence on when/why.

### Operation 2
\`\`\`bash
exact command here
\`\`\`

## Tips
[Edge cases, gotchas, composition with other skills]

Prefer curl + REST APIs over CLIs

Where possible, write skills that use curl against a REST API rather than wrapping a CLI tool. ShellLM minimizes installed dependencies. The SKILL.md is the abstraction layer.

Worth a CLI dependency when:

  • Auth flows require complex local state (OAuth, multi-step token exchange)
  • Significant client-side computation (signing, encryption)
  • The API has bizarre quirks the CLI smooths over

Declare requirements, don't manage secrets

If a skill needs an API key, declare it in requires.env. Do NOT prompt the user for the key or store it in a file. The user manages secrets via their shell environment or a secret manager.

Self-contained and composable

A good skill teaches the agent enough to use a tool without external docs. It should also compose -- if your skill produces JSON, the agent can pipe it to jq, etc.

Example: minimal skill

---
name: cowsay
description: Generate ASCII cow art with messages. Use when the user asks for cowsay or fun ASCII art.
metadata:
  shelllm:
    requires:
      bins: ["cowsay"]
---
# cowsay

## When to use
User asks for cowsay, ASCII art with a message, or fun text formatting.

## Common operations

### Say something
\`\`\`bash
cowsay "Hello, world!"
\`\`\`

### Use a different character
\`\`\`bash
cowsay -f tux "Linux rules"
\`\`\`

### List available figures
\`\`\`bash
cowsay -l
\`\`\`

### Pipe input
\`\`\`bash
echo "piped message" | cowsay
\`\`\`

Testing a skill

After writing, validate:

  1. skills check <name> -- requirements parse correctly
  2. skills show <name> -- content renders correctly
  3. Try a real prompt: <name> say "use the X skill to do Y" (your identity's persona command) and watch what the agent does
  4. Iterate based on whether the agent uses the skill correctly

Common mistakes

  • Description too vague -- skill never gets matched to user intent
  • Body too long -- wastes context window; keep under 1,000 tokens
  • Missing requires.env -- skill silently fails when API key isn't set
  • Writing for humans -- marketing language, badges, "why use this" sections
  • Hardcoding paths -- don't assume specific shell setup or directory structure
  • Not testing -- always verify what the agent actually does with the skill

After writing a new skill, place it in the skills directory and run skills check <name> to verify it parses and that requirements resolve correctly. If the skill needs to be available to other agents and users, propose adding it to the project's bundled skills or publishing it to a skills registry.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 8db84fd. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 months ago

README badge

README badge for laude-institute/headlong/skill-author