ClawdContext — Markdown OS for AI Coding Agents

Stop prompting. Start orchestrating.

ClawdContext is the complete VS Code toolkit for agentic AI development. It transforms your Markdown agent files into a governed operating system — combining deep context engineering (CER dashboard, kernel mapping, lessons lifecycle), advanced security scanning (SKILL.md verdicts, enterprise mTLS, strict file safety), and rich diagnostics (semantic contradiction detection, Lost-in-the-Middle, Kessler risk, kernel bloat analysis). Skill Forge Studio (built-in) guides you through creating production-quality SKILL.md files with AI-powered templates across 6 domains and 7 archetypes — online or fully offline. Works with OpenAI, Anthropic, Azure, Ollama, and DeepSeek. Every feature is designed for safe, scalable, and auditable agent workflows — governance, refactoring, and context health, all in one.

What you get (in one glance)

Core (no AI required)

• CER Dashboard + status bar — how much "always-loaded" context you burn vs. what's left for reasoning
• Markdown OS Linter — mdcc-style diagnostics across kernel, skills, lessons, and tasks
• Lessons Governance — TTL / staleness detection, metadata enforcement, prune / archive workflows
• SKILL.md Security Scanner — suspicious patterns + verdicts + per-skill security scores
• Refactors & Code Actions — extract procedure to SKILL.md, move heuristics to lessons, add missing metadata, archive deprecated entries

Optional AI (provider required)

• Explain diagnostics, detect semantic contradictions, validate agent files, suggest refactors, deep security review
• Works with OpenAI-compatible, Anthropic-compatible, Azure OpenAI, Ollama (local), and DeepSeek-compatible providers

Skill Forge Studio (new in 0.5.0)

• 8-step guided wizard to create production-quality SKILL.md files from scratch
• 6 domains (DevOps, Security, Data, Frontend, Backend, AI/ML) × 7 archetypes (Automator, Guardian, Analyst, Builder, Optimizer, Integrator, Specialist)
• Online mode — run the local backend for AI-powered generation with full control and privacy
• Offline mode — built-in templates work without any backend or network
• AI bridge — automatically reuses your extension AI provider settings for the backend
• Server lifecycle — auto-start/stop the Python backend from within VS Code

How to use Skill Forge Studio

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run ClawdContext: Create Skill with Skill Forge — opens the guided wizard
3. Follow the 8-step flow: name your skill, pick a domain, choose an archetype, define scope, and generate
4. The status badge shows your current mode: ● Online or ○ Offline
5. The generated SKILL.md is saved to your workspace — ready to use

Skill Forge modes explained

The extension tries the local backend first. If unreachable, it falls back to offline templates. No configuration needed — it just works.

Getting a fully working setup (5 minutes)

Skill Forge works out of the box in Offline mode (template-based, no setup needed). For AI-powered generation, follow these steps:

Step 1 — Configure your AI provider in VS Code

Open Settings (Cmd+, / Ctrl+,) and search for clawdcontext.ai:

This is the only place you configure API keys. They never leave your machine.

Step 2 — Start the local backend

Requirements: Python 3.12+

Option A — one command (recommended):

git clone https://github.com/yaamwebsolutions/clawdcontext.git
cd clawdcontext/skill_forge_studio
./run.sh   # macOS/Linux — creates venv, installs deps, starts on :8742

On Windows (PowerShell):

git clone https://github.com/yaamwebsolutions/clawdcontext.git
cd clawdcontext\skill_forge_studio
.\run.ps1

Option B — manual:

cd clawdcontext/skill_forge_studio
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn backend.main:app --reload --port 8742

Option C — Docker:

cd clawdcontext/skill_forge_studio
docker compose up -d

Step 3 — Verify

curl http://localhost:8742/health
# {"status":"ok","ai_available":true,...}

The extension detects the backend automatically — the badge switches to ● Online.

Step 4 — Create your first skill

1. Cmd+Shift+P → ClawdContext: Create Skill with Skill Forge
2. Follow the 8-step wizard: name, domain, archetype, scope, generate
3. Files are written to .clawdcontext/skills/<name>/ in your workspace

How it works: The extension forwards your AI provider settings to the local backend via the AI bridge. No .env file needed — VS Code settings are the single source of truth.

The model: what goes where

In 60 seconds

1. Open a repo containing any of: CLAUDE.md, AGENTS.md, SKILL.md, lessons.md, todo.md
2. Run ClawdContext: Analyze Workspace
3. Open ClawdContext: Open Dashboard and apply quick fixes from diagnostics
4. New repo? Run ClawdContext: Scaffold Markdown OS Templates

Diagnostics you'll actually see

• CER_CRITICAL · CER_WARNING
• KERNEL_BLOAT · PROCEDURE_IN_KERNEL · HEURISTIC_IN_KERNEL
• KESSLER_RISK · STALE_LESSON · MISSING_METADATA · DEPRECATED_PRESENT
• SKILL_NO_FRONTMATTER · SKILL_TOO_LARGE
• CONTRADICTION · LOST_IN_MIDDLE

Each diagnostic comes with a quick-fix code action when applicable.

Best commands (the 8 you'll use daily)

15 core commands + 11 AI commands + 4 OS/Skill Forge commands — 30 total. Full command list →

Safe-by-design write behavior

When AI is enabled, ClawdContext applies strict safety constraints:

• File paths validated via sanitizePath() — path traversal blocked (../, absolute paths)
• Only .md and .json files can be written
• User confirmation required before any file write
• Enterprise: mTLS client certs + custom CA + Azure OpenAI deployments

Privacy: what leaves your machine

No telemetry. No analytics. No tracking.

Minimal settings (start here)

Skill Forge (new in 0.5.0):

All settings: full configuration reference →

Install

code --install-extension clawdcontext.clawdcontext

Or search "ClawdContext" in the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).

What ClawdContext is / is not

Docs / Research

• Your AI Agent Has 200K Tokens of RAM — And You're Wasting 80% of It
• AGENTS.md evaluation paper (arXiv)
• SkillsBench (arXiv)

Development

git clone https://github.com/yaamwebsolutions/clawdcontext4vscode.git
cd clawdcontext4vscode
npm install
npm run compile

Press F5 in VS Code to launch the Extension Development Host.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• CODE_OF_CONDUCT.md · SECURITY.md · SUPPORT.md · ROADMAP.md

Star History

License

MIT

Yaam Web Solutions

Install · Report Issues · Discussions