Custom skill development

Why build custom Skills

When teams repeat a specialist workflow, wrap it as a Skill:

Reuse — everyone triggers it the same way
Consistency — process / standards / guardrails baked in
Evolution — bump versions, everyone benefits uniformly
Governance — security audit, permissions, usage analytics

Skill directory layout

my-skill/
├── SKILL.md              ← required: metadata + prompt (description + rules)
├── skill.manifest.json   ← optional: install config / version / deps
├── tools/                ← optional: skill-specific Python tools
│   └── my_tool.py
├── references/           ← optional: rules / templates / refs (lazy load)
│   └── checklist.md
├── tests/                ← optional: contract tests
│   └── test_contract.py
└── scripts/              ← optional: install / upgrade hooks

Authoring SKILL.md

Front matter (metadata)

---
name: my-skill
description: One or two sentences on *when* to invoke this skill. This is how the Agent decides.
execution_mode: balanced  # precise | balanced | creative
tags: [domain, usecase]
version: 1.0.0
license: proprietary      # proprietary | mit | apache-2.0
entrypoints:
  - name: main
    tools: [tools/my_tool.py:do_it]
---

Body (instructions for the Agent)

The body lands in system prompt or tool hints:

# my-skill
 
## When to use
- User says “do X”, “process Y document” etc.
- Do **not** trigger for pure conceptual Q&A.
 
## Steps
1. Read the input file.
2. Call tools/my_tool.py:do_it
3. Write output to the target path.
 
## Hard rules
- Do not mutate input files.
- Reject inputs >10 MB with a clear message.

description gates whether the Skill fires. The sharper it is, the fewer false positives.

Development workflow

1. Ideate — use skill-architect

/skill-architect Help me design a skill that generates test reports from Excel

skill-architect walks five stages: goal, triggers, I/O, constraints, risks — and emits a skeleton.

2. Scaffold

combo-cli skill init my-skill
# interactive name / description / entrypoints

3. Write SKILL.md

Center on description. Reference existing skills (e.g. AgentFlow/src/skills/builtin/docx/SKILL.md).

4. Optional dedicated tools

Place Python under tools/. Signatures surface to the Agent automatically:

def do_it(input_path: str, output_path: str, mode: str = "fast") -> dict:
    """Process a document.
 
    Args:
        input_path: Source file.
        output_path: Destination.
        mode: fast | accurate.
 
    Returns:
        {"status": "ok", "duration_ms": ...}
    """
    ...

5. Tests

# tests/test_contract.py
def test_happy_path():
    result = do_it("fixtures/sample.xlsx", "/tmp/out.xlsx")
    assert result["status"] == "ok"
 
def test_too_large():
    # should raise
    ...

6. Local debug

combo-cli skill run ./my-skill --input "process fixtures/sample.xlsx"

7. Publish

combo-cli skill publish ./my-skill --visibility tenant

Best practices

Tip	Detail
Sharp `description`	Spell out “invoke” vs “do not invoke”
Least privilege	Expose only needed tools
Rollback-safe	Provide dry-run and snapshots for writes
Abuse-resistant	Caps on size, rate, permissions
Reference, don’t inline	Large rules → `references/`, lazy load to save tokens
Idempotent	Same input → same outcome
Tests	Happy path + ≥2 failure paths

Anti-patterns

Stuffing business logic into SKILL.md (token-heavy)
Hard-coded secrets in Skills
Tools with uncontrolled side effects (global env mutation)
Tight coupling between Skills

Custom skill development

On this page