ai-agents-skills

AI Agents Skills

⚠️ Generated by an AI coding system — experimental. This repository's code, configuration, and documentation were generated by the same multi-agent AI coding system it installs skills for. It is experimental and may not work as expected outside the author's setup. For an overview of the whole system and how to try it, see the introductory blog post.

Shared, manifest-driven skills and settings for Codex, Claude, DeepSeek, CodeWhale, GitHub Copilot, OpenCode, Antigravity CLI, Grok, Kimi Code, ChatGPT Local Coder, and restricted OpenClaw fake-root targets.

System Summary

This is an experimental, personal-use configuration for research workflows, especially combinatorics and graph theory work. It is not a polished general product, and it may not behave as desired on other machines, other agent versions, or research tasks outside the assumptions documented here.

This repo turns a multi-agent research setup into one maintainable skill source. Codex, Claude, DeepSeek, CodeWhale, GitHub Copilot, OpenCode, Antigravity CLI, Grok, Kimi Code, and ChatGPT Local Coder can each load local skills. OpenClaw participates as a default fake-root-only target for normal installer flows, with a separate reviewed v2 skill-file path for real-system skill writes, an evidence-gated runtime-install path (the openclaw-runtime-* commands plus the host openclaw-broker) for real-system runtime files. Legacy dual-route /aas adapter copies may remain in an OpenClaw workspace, but the current publisher is blocked and does not inspect, replace, or remove those copies. This repository keeps the shared research workflows, profiles, delegation settings, dependency metadata, and installer logic in one place.

The research stack is organized as:

• agent frontends and targets: Codex, Claude, DeepSeek, CodeWhale, GitHub Copilot, OpenCode, Antigravity CLI, Grok, Kimi Code, ChatGPT Local Coder, and restricted OpenClaw
• shared skill source: manifest/, canonical/skills/, and targets/
• external capabilities: Python, TeX, optional SageMath, local library tools, document parsers, public databases, and retrieval helpers

For example, a literature-review request can route through research-briefing, deep-research-workflow, paper-lookup, and research-verification-gate; a paper-review request can check zotero first, fall back to calibre for books, parse files with docling, and then run paper-review.

Nontrivial research workflows are expected to keep evidence control visible: scope briefs define claim boundaries and goal/backward success checks, deep-research runs preserve source handoffs and guard outputs, delegated agents return bounded result packets, and final reports pass review and verification gates. The workflow tracks concrete issues and evidence gaps instead of hiding quality behind a single aggregate score.

Reusable failures, corrections, and missing capabilities route through self-improving-agent. That skill logs local .learnings/ entries and, when a lesson affects skills or settings, proposes a canonical repo integration plan that names affected install targets, OS/substrates, docs, manifests, runtime helpers, tests, and blocked coverage before any files are changed.

See docs/workflow-overview.md for the full sanitized system description and workflow examples.

Multi-agent work is documented separately in docs/multi-agent-examples.md. That page explains how the orchestrator selects templates, spawns bounded role agents, waits for round outputs, runs verification, and merges the result. It also covers the ARL hybrid model: host-owned panel phases around unattended drive (top-level provider CLIs for target advice and result review; the drive primary stays single-path math-only—see drive --panel on|auto|off). Template examples include:

• Lakatos Proof and Refutation: proof stress-testing.
• Polya Multi-Strategy Problem Solving: open problem exploration.
• Knuth Structured Manuscript Review: mathematical draft review.
• Structured Research Team: high-stakes claim and proof review.
• Graph Reconfiguration Specialist: gadgets, reductions, and PSPACE/NP-hardness checks.
• Lean Formalization Team: Lean skeleton and proof-blocker analysis.
• Prose / OpenProse-style workflow: reproducible decomposition and synthesis.

This repo is a generator and installer, not a copied dotfiles folder. It uses canonical skill names, generates per-agent adapters, supports partial installs, detects legacy/self-contained installs, and verifies only installed managed skills. Reusable skill bodies live under canonical/skills; default installs record the agent policy and fallback behavior used to choose symlink, reference, or copy mode. Copy mode remains available when an agent or filesystem must have regular files inside the settings directory.

Planning, prechecks, and runtime wrappers support Linux and Windows, with core POSIX installer flows also covered on macOS in CI. Native Windows target mutation is currently dry-run-only: apply, uninstall, rollback, OpenClaw target writes, and Antigravity settings writes fail closed until the mutation remains bound to the validated Windows handle. macOS users should expect POSIX-style behavior but lighter platform-specific guidance.

Documentation

• docs/source/index.md: docs-site landing page and task-oriented navigation.
• docs/installation.md: install, dry-run, conflict, and migration modes.
• docs/skills.md: skill catalog and descriptions.
• docs/artifacts.md: optional templates, instruction docs, personas, and entrypoint aliases.
• docs/profiles.md: selectable profiles such as research-core, full-research, complete-restore, and course-management.
• docs/course-management.md: Classroom50, Canvas, Google Classroom, and local roster DB agent skills (manual page).
• docs/external-dependencies.md: opt-in, pinned host-local provisioning for the Course Management Toolkit and VNU eOffice application packages (manual page).
• docs/dependencies.md: logical tools, current Linux/Windows extra software, Python packages, Node packages, and manual integrations.
• docs/lean-formalization.md: ordinary Lean/Lake, local or authorized remote execution, and separate evidence gates.
• docs/research-jobs.md: job choices, bounded recovery, pending verification, and resumption.
• docs/lax-formalization.md: per-paper Lean/Lax setup, independent verification, CI, secondary Zenodo archives, and migration.
• docs/lax-paper-workflow.md: executable job runbook for a new public repository, selected Lean reuse, TeX sanitation, paper versions and controller-bound readiness. Generated from the canonical workflow template.
• docs/lean-formalization-benchmarks.md: dated Lean benchmark survey and the separate bounded Lax workflow test.
• docs/restore-target-contract.md: restore target contract and evidence requirements.
• docs/workflow-overview.md: how agents, skills, runtimes, and research tools connect during real workflows.
• docs/multi-agent-examples.md: multi-agent process examples, spawn/wait lifecycle, and available research templates.
• docs/submission-venue-selector-plan.md: implementation plan for the fully automated submission venue selector skill.
• docs/system-profile.md: sanitized maintainer-system profile and how local tools map to skills.
• docs/agent-locations.md: supported agent config, skill, template, command, persona, and tool-shim locations.
• docs/surfaces.md: generated target-surface support states, render mechanisms, and claim basis.
• docs/local-library-profiles.md: local Zotero/Calibre discovery, profile selection, and mutation safety rules.
• docs/audit-and-migration.md: audit output, staged migration, unmanaged local skill handling, and Windows-native verification notes.
• docs/openclaw-integration-plan.md: gated OpenClaw integration plan, risk fixes, and acceptance criteria.
• docs/openclaw-install-target-plan.md: restricted OpenClaw-as-install-target policy, v2 skill-file gate, phases, and tests.
• docs/verification.md: installed-artifact verification model.
• docs/architecture.md: manifest-to-target rendering, install modes, artifact classes, and safety boundaries.
• docs/windows.md and docs/linux.md: platform-specific command and dependency notes.
• docs/troubleshooting.md: common install, audit, launcher, migration, and verification cases.
• docs/uninstall-rollback.md: scoped uninstall and rollback behavior.

The GitHub Pages site is built from docs/source and deployed by .github/workflows/docs.yml.

Most checked-in docs are generated. Edit installer/ai_agents_skills/docs.py and the manifests for generated pages, then run make docs; CI checks that generated docs are current. Generated docs are README.md, each page emitted by generated_doc_texts() under docs/, and the mirrored copies under docs/source/. The source-only docs/source/index.md and docs/source/overview.md are maintained manually. Manual pages with matching copies under both docs/ and docs/source/ are submission-venue-selector-plan.md, course-management.md, external-dependencies.md, restore-target-contract.md, and lean-formalization-benchmarks.md; keep each pair in sync. docs-check checks generated text consistency, not the factual correctness of the instructions. The Lax paper workflow page is rendered from canonical/templates/lax-paper-workflow.md; edit that template for its contents.

Acknowledgements

This repository was implemented and maintained with help from coding agents, including:

• OpenAI Codex (ChatGPT Codex)
• Anthropic Claude (Claude Code)
• xAI Grok
• DeepSeek (CodeWhale)
• GitHub Copilot
• OpenCode
• Antigravity CLI
• Kimi Code

Human direction, review, and release decisions remain with the maintainer. Install targets may also include restricted OpenClaw-shaped environments; those are not claimed as primary coding agents for this repository's authorship.

License

This project is licensed under GPL-3.0-or-later. See LICENSE.

Quick Start

Clone the repo and run commands from the repository root:

git clone https://github.com/hoanganhduc/ai-agents-skills.git
cd ai-agents-skills

Requires Python 3.10 or newer. Linux and macOS examples use make and the POSIX bootstrap script. Windows examples use ./make.ps1, which requires pwsh or powershell.exe. The installer normally plans targets for existing agent homes; absent homes are normally reported and skipped. ChatGPT Local Coder is an exception: detected runtime config or its CLI can qualify the target for creation of ~/.chatgpt-local-coder during an approved install. See Agent Locations.

Linux/macOS:

make doctor
make precheck ARGS="--profile research-core"
make audit-system ARGS="--profile research-core"
make list-skills
make list-artifacts
make plan ARGS="--profile research-core"
make plan ARGS="--no-skills --artifact-profile workflow-templates"
make install ARGS="--profile research-core --dry-run"
make lifecycle-test ARGS="--matrix default --platform-shape all"
make fake-root-lifecycle ARGS="--profile research-core --platform-shape linux"

For a macOS-shaped fake-root check, use --platform-shape macos in the final command.

Windows:

./make.ps1 doctor
./make.ps1 precheck --profile research-core
./make.ps1 audit-system --profile research-core
./make.ps1 list-skills
./make.ps1 list-artifacts
./make.ps1 plan --profile research-core
./make.ps1 plan --no-skills --artifact-profile workflow-templates
./make.ps1 install --profile research-core --dry-run

Lifecycle tests perform real writes inside fake roots and are blocked on native Windows too. Run Windows-shaped lifecycle tests from Linux/WSL; see Windows. This checks path/layout behavior, not native mutation.

For a shorter first pass, run doctor, precheck, plan, and a dry-run install before any lifecycle matrix. lifecycle-test and fake-root-lifecycle are verification tools; they use fake roots and should not be confused with a real install.

Applied installs, uninstalls, and rollbacks are interactive: before any --apply writes files, the installer explains the install, uninstall, and rollback process and requires the user to type the displayed confirmation phrase. Real-system writes also require explicit --apply --real-system. Tests and examples use fake roots. Existing unmanaged files are skipped by default; use --adopt, --backup-replace, or --migrate only after reviewing plan output.

After reviewing plan output, a real install uses both write gates:

make install ARGS="--profile research-core --apply --real-system"

For the closure-complete, non-OpenClaw component of a machine restoration, use the wildcard complete-restore profile, the exhaustive workflow-artifacts profile, the full portable runtime, exact target enforcement, and complete action enforcement. The command fails before writing if any requested agent home is absent or any requested action has an unresolved conflict. Explicit manifest-declared platform-inapplicable support files and Antigravity alias collisions with the managed skill surface are recorded as declared neutral exclusions:

export AAS_RESTORE_AGENTS="codex,claude,deepseek,codewhale,copilot,opencode,antigravity,grok,kimi,chatgpt-local-coder"
make plan ARGS="--agents $AAS_RESTORE_AGENTS --profile complete-restore --artifact-profile workflow-artifacts --runtime-profile full --require-all-requested-agents"
make install ARGS="--agents $AAS_RESTORE_AGENTS --profile complete-restore --artifact-profile workflow-artifacts --runtime-profile full --require-all-requested-agents --require-complete-install --apply --real-system --post-install-smoke verify"

The example lists all ten non-OpenClaw registry targets. Before running it, choose only targets actually present and intended on this machine; --require-all-requested-agents is an assertion, not permission to add absent agents. ChatGPT Local Coder uses the detection exception described below.

An outer restoration system should close software and Python dependencies next, then run make installed-runtime-smoke ARGS="--require-complete-coverage". OpenClaw is intentionally excluded from this target list: real OpenClaw restoration remains delegated to its reviewed component/manifests and is not written by this complete-restore flow.

Skills install in --install-mode auto by default so the repo remains the single maintained source without hiding agent-loader differences. plan --json shows the effective mode, agent policy evidence, apply-time symlink fallback, and reason for each target. Explicit modes apply only to supported targets: Copilot rejects forced symlinks; OpenClaw rejects symlink and reference modes. Use --install-mode copy when files must be materialized inside the agent home.

Optional workflow artifacts are not installed by default. Use --artifact-profile workflow-templates, --artifact-profile review-personas, --artifact-profile workflow-instructions, or --artifact-profile research-entrypoints explicitly. Use --with-deps when dependency-bound artifacts should also install their backing skills.

Command Surfaces

• make <target> ARGS="..." is the normal Linux/macOS wrapper.
• ./make.ps1 <command> ... is the normal native Windows wrapper.
• ./installer/bootstrap.sh <command> ... and python3 -m installer.ai_agents_skills <command> ... are direct POSIX entrypoints for installer CLI commands when debugging wrapper behavior.
• Installer CLI commands include doctor, precheck, audit-system, plan, install, verify, smoke, rollback, uninstall, runtime-smoke, installed-runtime-smoke, lifecycle-test, list-skills, list-artifacts, describe, describe-artifact, provision-external, provision-skill-python, verify-skill-python, and docs-check.
• Makefile-only maintainer targets include docs, docs-site, static-check, sanitize-check, test, and release-check; run them through make or ./make.ps1, not as installer CLI commands.

Runtime-Backed Skills

Runtime-backed skills install shared helper files from canonical/runtime into a root-scoped runtime directory instead of copying executable helpers inside every agent's skill directory. The runtime manifest declares platform filters, newline policy, executable modes, and the exact source-to-target mapping. Runtime inventory intentionally rejects live config, databases, caches, downloaded documents, bytecode, archives, symlinks, sensitive material, and persistent execution markers.

slides-to-video is a runtime-backed skill that turns prepared slides (PNG/PDF/PPTX) into a narrated, captioned MP4 in a chosen language and presenter role using only free tools (edge-tts/Kokoro/Piper plus ffmpeg). It runs a three-phase, human-in-the-loop flow and blocks rendering until the transcript is explicitly approved. English and Vietnamese are first-class; other languages are supported generically. See docs/skills.md and the skill references.

Docling is the main document/OCR runtime-backed skill. Its managed wrapper is local-only by default: sources must be local files and remote service fields are rejected from config. Use scan-heavy when you want stronger local OCR for image-backed papers. Execute run_skill.sh directly so its #!/bin/bash -p shebang takes effect:

"${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" skills/docling/run_docling.sh doctor
"${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" skills/docling/run_docling.sh convert \
  --source "/path/to/paper.pdf" \
  --to md \
  --preset scan-heavy

OCR.space fallback is available only through explicit remote upload flags:

"${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" skills/docling/run_docling.sh convert \
  --source "/path/to/paper.pdf" \
  --to md \
  --preset scan-heavy \
  --ocr-fallback ocrspace \
  --allow-remote-ocr

To test the live OCR.space adapter, run the explicit smoke command. It generates and uploads a synthetic one-page PDF, not a user document:

"${AAS_RUNTIME_ROOT:-$HOME/.local/share/ai-agents-skills/runtime}/run_skill.sh" skills/docling/run_docling.sh ocrspace-smoke \
  --allow-remote-ocr

Docling config can be passed with --config, AAS_DOCLING_CONFIG, DOCLING_CONFIG, or $AAS_RUNTIME_WORKSPACE/config/docling.toml. The runtime skill directory includes docling.example.toml; live config files and OCR.space keys stay outside the managed manifest.

Profiles

Profiles are named presets for installing groups of related skills. Use a profile when you want a workflow bundle instead of selecting every skill by hand. For example, research-core installs the normal research planning/source/review/delivery path, while full-research selects every canonical research skill.

make plan ARGS="--profile research-core"
make install ARGS="--profile research-core --dry-run"

Browse the skill profiles.

Artifact Profiles

Artifact profiles install optional support files outside normal skill folders: templates, instruction docs, reviewer personas, entrypoint aliases, and repo-management notices. They are opt-in because these files can affect agent behavior more broadly than a single skill.

make plan ARGS="--no-skills --artifact-profile workflow-templates"
make plan ARGS="--no-skills --artifact-profile repo-management"

Use --with-deps when selected artifacts should also bring in the backing skills they depend on. Use --with-recommended-templates for the reverse: when installing skills, also install each skill's curated recommended template(s) (e.g. tikz-draw -> tikz-figure-verification-runbook, autonomous-research-loop -> autonomous-research-loop-runbook). It is opt-in, so default installs are unchanged.

Browse the artifact profiles.

Skills

Skills are the installable agent capabilities. Installing a skill creates the per-agent SKILL.md target, support files when needed, and managed instruction blocks only for installed, adopted, or migrated skills. By default those skill targets follow auto mode: Claude links to canonical/skills; Codex, CodeWhale, OpenCode, Grok, Kimi Code, and ChatGPT Local Coder receive copied native skill files plus support files; Grok installs under ~/.grok and disables its [compat.claude] ride-along for a self-contained view; Kimi installs under ~/.kimi-code and does not auto-edit config.toml. DeepSeek receives reference adapters, and Antigravity receives copied flat global Markdown skills plus native plugin/config scaffolds. Vendor-migrated homes use ~/.gemini/config/skills and ~/.gemini/config/plugins; settings remain in the legacy CLI home. Explicit symlink, reference, and copy modes select a strategy only for supported targets: Copilot blocks symlink mode, and OpenClaw blocks symlink and reference modes. Use --skill or --skills for narrow installs.

make plan ARGS="--skill zotero"
make install ARGS="--skills zotero,docling --dry-run"

Browse the complete skill catalog.