Developing Claude Code Skills
Relevant source files
The following files were used as context for generating this wiki page:
Developing Claude Code Skills involves creating reusable capabilities within the Continuous Claude ecosystem to automate workflows and manage session context efficiently. In this project, "Skills" refer specifically to the native Claude Code format (found in .claude/skills/), which often act as high-level wrappers around lower-level Python "Scripts" (found in scripts/) to achieve significant token and time reductions.
The development architecture follows a "Scripts-Based Execution" philosophy, where complex logic is offloaded to CLI-driven Python scripts to maintain a lightweight context. This approach achieves up to a 99.6% token reduction by avoiding the need for Claude to write or read large amounts of code repeatedly within the conversation.
Sources: CLAUDE.md:4-8, scripts/SCRIPTS.md:3-12, scripts/README.md:5-10
Skill vs. Script Architecture
The system distinguishes between Skills and Scripts. Skills are the entry points for the Claude Code agent, while Scripts provide the heavy-lifting orchestration logic.
Technical Definitions
- Skills: Native Claude Code format stored in
.claude/skills/<name>/SKILL.md. These are auto-discovered by the agent and define "When to Use" and "When NOT to Use" metadata. - Scripts: Agent-agnostic CLI-based Python workflows stored in
scripts/. They utilizeargparseto handle parameters, allowing the agent to execute complex tasks by simply passing arguments rather than modifying code.
Sources: CLAUDE_ONBOARDING.md:126-130, scripts/README.md:14-25
Workflow Discovery and Execution
The following diagram illustrates how the Claude Code agent interacts with the codebase to discover and execute a capability.
This discovery-first flow ensures that the agent utilizes existing logic efficiently.
Sources: scripts/SCRIPTS.md:21-30, CLAUDE.md:30-38
Developing New Skills
To add a new capability to the Continuous Claude kit, developers must follow specific patterns for scripts and skills to ensure they are properly integrated and token-efficient.
CLI-Based Script Template
New scripts must be designed as reusable CLI workflows. They utilize the runtime.harness for execution, which manages the Model Context Protocol (MCP) initialization and signal handling.
"""
SKILL: {Name}
DESCRIPTION: {What it does}
CLI ARGUMENTS:
--param1 Description
USAGE:
uv run python -m runtime.harness scripts/{skill}.py --param1 "value"
"""
import argparse
import asyncio
import sys
def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("--param1", required=True)
# Filter out script path from sys.argv for harness compatibility
args_to_parse = [arg for arg in sys.argv[1:] if not arg.endswith(".py")]
return parser.parse_args(args_to_parse)
async def main():
args = parse_args()
# Logic implementation
Sources: scripts/SCRIPTS.md:65-100, scripts/README.md:55-75
Tool Safety and Parameter Generation
When developing scripts that interface with MCP tools, the system includes logic to classify tool safety and automatically generate test parameters. This is handled by src/runtime/generate_test_params.py.
| Component | Logic Source | Description |
|---|---|---|
| Classification | classify_tool | Categorizes tools as SAFE, DANGEROUS, or UNKNOWN based on regex patterns (e.g., get_ is safe, delete_ is dangerous). |
| Discovery | build_discovery_config | Connects to servers to introspect tool schemas and build a safe list for the agent. |
| Generation | generate_test_parameters | Uses Claude API or CLI to create valid, minimal JSON payloads for tool testing. |
Sources: src/runtime/generate_test_params.py:74-105, src/runtime/generate_test_params.py:317-350
Skill Development Principles
Developers must adhere to several key principles to maintain the project's efficiency and offline-first philosophy.
- Logic Mutability, Parameter Immutability: Edit skills to fix bugs or improve logic, but use CLI arguments to change how they run. Avoid editing files just to change a search query or URL.
- Defensive Coding: For tool outputs, always use defensive coding (e.g., fallback values) as tool responses can vary.
- Local-First: All skills must have local alternatives. If a skill requires an API key (like Firecrawl), a local fallback (like
trafilatura) should be provided and documented. - Small Footprint: Keep
SKILL.mdfiles under 200 lines to minimize context overhead.
Sources: scripts/SCRIPTS.md:13-19, scripts/SCRIPTS.md:175-182, CLAUDE_ONBOARDING.md:126-130
Extension Points
New capabilities can be added at different layers of the system:
| Extension Point | Location | Requirement |
|---|---|---|
| Claude Skill | .claude/skills/<name>/SKILL.md | Follow standard markdown/YAML structure. |
| MCP Script | scripts/<name>.py | Must use argparse for all inputs. |
| Event Hook | .claude/hooks/<name>.sh | Shell wrapper pointing to TypeScript/JS handler. |
| Rule | .claude/rules/<name>.md | YAML frontmatter + behavioral markdown. |
Sources: CLAUDE_ONBOARDING.md:113-120, install-global.sh:425-430
Summary
Developing skills for Continuous Claude requires a shift from direct conversation-based task execution to a script-orchestrated workflow. By building reusable CLI scripts and wrapping them in auto-discovered Claude Skills, developers ensure the system remains fast, token-efficient, and capable of handling complex multi-tool pipelines while maintaining a 100% offline operational mode.
Sources: CLAUDE.md:120-130, scripts/SCRIPTS.md:185-195