Command Code

What are Agent Skills?

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.

my-skill/ ├── SKILL.md # Required: instructions + metadata ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation └── assets/ # Optional: templates, resources

How skills work?

Skills use progressive disclosure to manage context efficiently:

  1. Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.

  2. Activation: When a task matches a skill's description, the agent reads the full SKILL.md instructions into context.

  3. Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.

This approach keeps agents fast while giving them access to more context on demand.

The SKILL.md file

Every skill starts with a SKILL.md file containing YAML frontmatter and markdown instructions:

--- name: pdf-processing description: Extract text and tables from PDF files, fill forms, merge documents. --- # PDF Processing ## When to use this skill Use this skill when the user needs to work with PDF files... ## How to extract text 1. Use pdfplumber for text extraction... ## How to fill forms ...

The following frontmatter is required at the top of SKILL.md:

  • name: A short identifier
  • description: When to use this skill

The markdown body contains the actual instructions and has no specific restrictions on structure or content.

This simple format has some key advantages:

  • Self-documenting: A skill author or user can read a SKILL.md and understand what it does, making skills easy to audit and improve.

  • Extensible: Skills can range in complexity from just text instructions to executable code, assets, and templates.

  • Portable: Skills are just files, so they're easy to edit, version, and share.

Command Code implementation

Command Code stores skills in two locations:

User-level skills (global)

Location: ~/.commandcode/skills/

Available across all your projects. Perfect for personal preferences and general workflows.

Create a user-level skill

mkdir -p ~/.commandcode/skills/code-review cat > ~/.commandcode/skills/code-review/SKILL.md << 'EOF' --- name: code-review description: Perform thorough code reviews checking for bugs, security, and best practices --- # Code Review Check for: - Security issues - Code quality - Performance - Testing EOF

Project-level skills (local)

Location: .commandcode/skills/ (in your project root)

Available only within that specific project. Perfect for team conventions and project-specific patterns.

Create a project-level skill

mkdir -p .commandcode/skills/api-guidelines cat > .commandcode/skills/api-guidelines/SKILL.md << 'EOF' --- name: api-guidelines description: API design patterns and conventions for this project --- # API Guidelines Follow these patterns when creating APIs... EOF

Browsing skills

Use the /skills slash command in Command Code to browse all available skills:

# In Command Code session /skills

This opens an interactive menu showing:

  • All your user-level skills marked with (user)
  • All project-level skills marked with (project)
  • Skill names and descriptions

Navigate with arrow keys, press Enter to open a skill in your editor, or Esc to close.

Specification

Frontmatter (required)

--- name: skill-name description: A description of what this skill does and when to use it. ---

With optional fields:

--- name: pdf-processing description: Extract text and tables from PDF files, fill forms, merge documents. license: Apache-2.0 compatibility: Requires pdfplumber and PyPDF2 packages metadata: author: example-org version: "1.0" allowed-tools: Read Bash(python:*) ---
FieldRequiredConstraints
nameYesMax 64 characters. Lowercase letters, numbers, and hyphens-separated only. Must not start or end with a hyphen.
descriptionYesMax 1024 characters. Non-empty. Describes what the skill does and when to use it.
licenseNoLicense name or reference to a bundled license file.
compatibilityNoMax 500 characters. Indicates environment requirements (packages, system tools, network access, etc.).
metadataNoArbitrary key-value mapping for additional metadata (author, version, etc.).
allowed-toolsNoSpace-delimited list of pre-approved tools the skill may use. (Experimental)

name field

The required name field:

  • Must be 1 to 64 characters
  • May only contain lowercase alphanumeric characters and hyphens (a-z and -)
  • Must not start or end with -
  • Must not contain consecutive hyphens (--)
  • Must match the parent directory name

Valid examples:

name: pdf-processing name: data-analysis name: code-review

Invalid examples:

name: PDF-Processing # uppercase not allowed name: -pdf # cannot start with hyphen name: pdf--processing # consecutive hyphens not allowed

description field

The required description field:

  • Must be 1 to 1024 characters
  • Should describe both what the skill does and when to use it
  • Should include specific keywords that help Command Code identify relevant tasks

Good example:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Poor example:

description: Helps with PDFs.

license field

The optional license field specifies the license applied to the skill:

license: MIT
license: Proprietary. See LICENSE.txt for complete terms

compatibility field

The optional compatibility field indicates environment requirements:

compatibility: Requires git, docker, and jq
compatibility: Designed for Command Code. Requires internet access.
Note

Most skills do not need the compatibility field.

metadata field

The optional metadata field stores additional properties:

metadata: author: example-org version: "1.0" maintainer: team@example.com

allowed-tools field

The optional allowed-tools field lists pre-approved tools (experimental):

allowed-tools: Bash(git:*) Bash(jq:*) Read Grep

Body content

The markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps Command Code perform the task effectively.

Recommended sections:

  • When to use this skill: Clear triggers for activation
  • Step-by-step instructions: Detailed guidance
  • Examples: Input/output examples
  • Common edge cases: Known pitfalls and solutions
Note

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files in references/.

Optional directories

scripts/

Contains executable code that agents can run. Scripts should:

  • Be self-contained or clearly document dependencies
  • Include helpful error messages
  • Handle edge cases gracefully
my-skill/ ├── SKILL.md └── scripts/ ├── extract.py └── process.sh

references/

Contains additional documentation that agents can read when needed:

my-skill/ ├── SKILL.md └── references/ ├── API_REFERENCE.md ├── FORMS.md └── TROUBLESHOOTING.md

Keep individual reference files focused. Command Code loads these on demand, so smaller files mean less context usage.

assets/

Contains static resources:

my-skill/ ├── SKILL.md └── assets/ ├── template.json ├── diagram.png └── schema.sql

Progressive disclosure in action

Here's how Command Code uses a skill:

Startup (all skills):

Skills loaded: code-review, api-guidelines, testing-patterns Total tokens: ~300 (just names + descriptions)

User asks: "Review this code for security issues"

Command Code thinks: "This matches 'code-review' skill description"

Command Code loads:

--- name: code-review description: Perform thorough code reviews... --- # Code Review Checklist ## Security - [ ] No hardcoded credentials - [ ] Input validation ...

Result: Command Code follows the security checklist from the skill, ensuring consistent, thorough reviews.

Standard compliance

Command Code fully implements the Agent Skills open standard. Skills you create are:

  • Portable: Work with any agent that supports the standard
  • Versionable: Track changes with Git
  • Shareable: Publish for your team or community
  • Auditable: Plain text files anyone can read

Next steps