Cognitive Toolworks

Generate cross-platform agent artifacts (SKILL.md, AGENTS.md) using LLM intelligence.

Quick Start (60 seconds)

pip install -e .                    # Install
ct ls                               # List 80 skills
ct search kubernetes                # Find skills
ct show <slug> --full               # View details
ct validate ./skills/<slug>/        # Validate skill

Need LLM generation? Set ANTHROPIC_API_KEY then: ct generate skill --from-mcp config.json

Transform MCP servers and repositories into SKILL.md and AGENTS.md files compatible with Claude, Codex, Gemini, and other AI agents.

What's Included

This repository contains:

80 production-ready skills covering security, cloud, DevOps, testing, and more
18 orchestrator agents that coordinate multiple skills for complex workflows
CLI tooling to generate, validate, and manage your own skills

Getting Started

Prerequisites

Python 3.11 or higher
Git
(Optional) ANTHROPIC_API_KEY for LLM-powered generation

Installation

# Clone the repository
git clone https://github.com/williamzujkowski/cognitive-toolworks.git
cd cognitive-toolworks

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install
pip install -e .

# Verify installation
ct version

Your First Commands

# Explore available skills (no API key needed)
ct ls                           # List all 80 skills
ct search kubernetes            # Search for skills
ct show security-appsec-validator  # View skill details

# Validate a skill
ct validate ./skills/api-design-validator/

# Generate a skill from a README (no API key needed)
ct generate skill --from-readme ./README.md --name my-skill --output ./my-skill/

Feature Status

Feature	Status	API Key Required
Skill Discovery (`ct ls`, `ct search`, `ct show`)	Stable	No
MCP Introspection (`ct introspect mcp`)	Stable	No
OpenAPI Introspection (`ct introspect openapi`)	Stable	No
README Source (`ct generate skill --from-readme`)	Stable	No
Skill Validation (`ct validate`)	Stable	No
Security Scanning (`ct security-scan`)	Stable	No
Skill Generation (`ct generate skill --from-mcp`)	Stable	Yes
Skill Optimization (`ct optimize`)	Stable	Yes
AGENTS.md Generation (`ct generate agents-md`)	Beta	Yes

Using Skills & Agents

How Skills Work

Skills are self-contained instruction sets that teach AI agents how to perform specific tasks. Each skill follows the Anthropic SKILL.md format with:

Trigger conditions: When the skill should activate
Procedures: Step-by-step instructions (T1/T2/T3 tiers)
Quality gates: Validation rules and constraints

Browsing Skills

# List all skills
ct ls

# Filter by domain
ct ls --domain security    # 11 security skills
ct ls --domain cloud       # 8 cloud architecture skills
ct ls --domain testing     # 5 testing skills

# Search across all skills
ct search "API design"
ct search kubernetes

# View full skill details
ct show api-graphql-designer --full

How Agents Work

Agents are orchestrators that coordinate multiple skills to complete complex workflows. They follow a 4-step pattern:

Plan: Parse request, identify required skills
Execute: Invoke skills in sequence
Validate: Check outputs against quality gates
Report: Return structured results

# View agents index
cat index/agents-index.json | jq '.[] | .slug'

# View agent details
ct show cloud-aws-orchestrator --full

CLI Integration

Make skills available to your AI coding assistants:

Claude Code

Claude Code auto-discovers skills from ~/.claude/skills/ and agents from ~/.claude/agents/.

# Recommended: Use sync script for global installation
./scripts/sync-to-claude.sh

# This creates symlinks with ct- prefix:
#   ~/.claude/skills/ct-api-design-validator → ./skills/api-design-validator/
#   ~/.claude/agents/ct-security-auditor.md → ./agents/security-auditor/AGENT.md

# To uninstall:
./scripts/sync-to-claude.sh --uninstall

After syncing, skills and agents are auto-discoverable:

Skills: Claude uses them automatically based on context
Agents: Available via Task(subagent_type="ct-security-auditor", ...)

Verify: Ask Claude Code "What skills are available?" or check ls ~/.claude/skills/ct-*

Codex CLI

Codex CLI uses AGENTS.md for project instructions and supports fallback files.

# This repo already includes AGENTS.md - Codex will discover it automatically

# To also support CLAUDE.md, add to ~/.codex/config.toml:
# project_doc_fallback_filenames = ["CLAUDE.md", "AGENTS.md"]

Gemini CLI

Gemini CLI uses GEMINI.md hierarchy with configurable context files.

# Option 1: Create settings to recognize AGENTS.md
mkdir -p ~/.gemini
cat > ~/.gemini/settings.json << 'EOF'
{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}
EOF

# Option 2: Create project-level GEMINI.md
cp AGENTS.md GEMINI.md

CLI Reference

Discovery Commands

ct ls                              # List all skills
ct ls --domain <domain>            # Filter by domain
ct ls --format json                # JSON output

ct search <term>                   # Search skills/agents
ct search <term> --format json     # JSON output

ct show <slug>                     # View skill/agent summary
ct show <slug> --full              # View complete skill/agent

Generation Commands

# Generate skill from MCP server (requires API key)
ct generate skill --from-mcp config.json --output ./my-skill/

# Generate skill from README (no API key)
ct generate skill --from-readme README.md --name my-skill --output ./my-skill/

# Generate skill from OpenAPI spec (requires API key)
ct generate skill --from-openapi spec.json --output ./my-skill/

# Generate AGENTS.md for a repository (requires API key)
ct generate agents-md --repo . --output ./AGENTS.md

Validation Commands

ct validate ./path/to/skill/       # Validate skill structure
ct validate ./skill/ --verbose     # Verbose output
ct validate ./skill/ --platforms anthropic,openai  # Multi-platform

ct analyze ./path/to/skill/        # Token and quality analysis
ct analyze ./skill/ --full-report  # Detailed report

ct security-scan ./skills/         # Scan for security issues
ct security-scan ./skills/ --recursive  # Recursive scan

Optimization Commands

# Preview optimization (requires API key)
ct optimize ./my-skill/ --tier T2 --dry-run

# Apply optimization in-place
ct optimize ./my-skill/ --tier T2 --in-place

Introspection Commands

# Extract tool definitions from MCP server
ct introspect mcp config.json --output analysis.json

# Extract endpoints from OpenAPI spec
ct introspect openapi spec.json --output analysis.json

Architecture

Sources          →   LLM Analysis   →   Generation   →   Validation
─────────────────────────────────────────────────────────────────────
• MCP Server         Semantic           SKILL.md        Anthropic
• OpenAPI Spec       Analysis           AGENTS.md       OpenAI
• README             Workflows          llms.txt

Design Principles:

Progressive Disclosure: T1 (≤2k tokens) → T2 (≤6k tokens) → T3 (≤12k tokens)
Cross-Platform: Generate once, validate for Anthropic and OpenAI
Security-First: Pattern detection for credentials, shell injection, file access

Security

Built-in security scanning detects:

Unrestricted file system access
Network calls without allowlisting
Shell command injection vectors
Sensitive data exposure

ct security-scan ./skills/ --recursive

Claude Code Integration

This repository includes Claude Code slash commands:

# Available in Claude Code CLI
/skill-validate   # Validate a skill against CLAUDE.md standards
/skill-create     # Create a new skill with proper structure
/skill-search     # Search skills index
/generate-skill   # Generate skill from various sources
/rebuild-index    # Rebuild skills and agents indices
/run-maintenance  # Run full maintenance workflow

Slash commands are defined in .claude/commands/.

See llms.txt for LLM-friendly project overview.

Instruction Files

This repository uses a centralized architecture for AI assistant instructions:

AGENTS.md (Canonical Source)
├── Universal dev workflow (60k+ tool support)
├── Setup, testing, PR, coding conventions
└── Imported by CLI-specific files

CLAUDE.md (Skills Meta-Rules)              GEMINI.md (Gemini Wrapper)
├── @./AGENTS.md import                    ├── @./AGENTS.md import
├── Naming conventions (§2A)               └── Gemini-specific commands
├── Token budgets (§0A-0C)
└── SKILL.md format (§3)

File	Purpose	Tool Support
AGENTS.md	Canonical development workflow	Codex, Cursor, Aider, 60k+ tools
CLAUDE.md	Skills/agents library meta-rules	Claude Code
GEMINI.md	Gemini CLI wrapper	Gemini CLI

When to Update Each

Change Type	Update File
Dev workflow, testing, PR format	AGENTS.md
Skill naming, token budgets, SKILL.md format	CLAUDE.md
Gemini-specific CLI commands	GEMINI.md

Validation

# Run all checks (tokens, imports, conflicts, cross-refs)
python tooling/validate_instructions.py --all

# Check specific aspects
python tooling/validate_instructions.py --check-chain    # Import chain
python tooling/validate_instructions.py --check-conflicts # PR format conflicts

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# Setup development environment
pip install -e ".[dev]"
pre-commit install

# Run tests
pytest

# Run linting
ruff check . && ruff format . && mypy src/

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

Built for the AI agent ecosystem:

Made by William Zujkowski

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.claude/commands		.claude/commands
.github		.github
agents		agents
docs		docs
index		index
scripts		scripts
skills		skills
src/cognitive_toolworks		src/cognitive_toolworks
tests		tests
tooling		tooling
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
llms.txt		llms.txt
pyproject.toml		pyproject.toml

License

williamzujkowski/cognitive-toolworks

Folders and files

Latest commit

History

Repository files navigation

Cognitive Toolworks

Quick Start (60 seconds)

What's Included

Getting Started

Prerequisites

Installation

Your First Commands

Feature Status

Using Skills & Agents

How Skills Work

Browsing Skills

How Agents Work

CLI Integration

Claude Code

Codex CLI

Gemini CLI

CLI Reference

Discovery Commands

Generation Commands

Validation Commands

Optimization Commands

Introspection Commands

Architecture

Security

Claude Code Integration

Instruction Files

When to Update Each

Validation

Contributing

License

Acknowledgments

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Uh oh!

Contributors 2

Uh oh!

Languages