Skills on KnightLi Blog

A Survey of Mainstream AI PPT Tools: How to Choose Between Auto Generation, Web Slides, PPTX, and Image-Based Workflows

Mon, 18 May 2026 22:29:43 +0800

AI for PPT is no longer just “enter a title and apply a template.” In AI coding environments such as Claude Code, Codex, and Cursor, PPT generation is becoming a set of installable, reusable Agent Skills: some output web presentations, some generate truly editable .pptx files, some use image models to turn each slide into a visual draft, and some let AI operate PowerPoint files through MCP.

This article looks at a group of mainstream PPT-related Skills. The useful part is not only the list itself, but the way these tools can be separated by delivery format. Before choosing a tool, ask one question first: who will edit the final deliverable, where will it be presented, and does it need ongoing collaboration?

Several Routes

1. HTML Web Presentations

Representative projects include frontend-slides, guizang-ppt-skill, and html-ppt-skill.

The strength of this route is visual expressiveness. CSS animations, Canvas, WebGL, and responsive layouts are all available. The result can be opened directly in a browser, making it suitable for technical talks, product launches, Demo Day presentations, and talks with a strong personal style.

The trade-off is also clear: after delivery, it is not ideal for clients who need to edit text line by line. If the client receives HTML instead of a PowerPoint file, later changes often need to go back through the generation workflow.

If you only care about HTML presentations, frontend-slides feels like a high-star general entry point, guizang-ppt-skill is stronger in aesthetic constraints and themed style, and html-ppt-skill stands out for its number of themes, layout options, and presenter mode.

2. Native PPTX

Representative projects include mckinsey-pptx, ppt-agent-skills, claude-office-skills, and ppt-master.

This is the most stable route for business delivery. As long as the client asks to “edit text, change images, and apply a company template in PowerPoint,” the final output needs to land in .pptx.

ppt-master is especially worth a separate look. Its idea is to have the LLM generate SVG first, then convert it into native PowerPoint DrawingML objects. The goal is to keep text boxes, shapes, and charts editable inside PPTX. It also supports generating PPTX from PDF, DOCX, URL, and Markdown, as well as template replication, animation, narration, and local preview.

This route works well for consulting deliverables, company reports, white paper presentations, and turning long reports into PPT decks. The downside is that the visual ceiling is usually limited by PowerPoint itself, so complex effects are not as free as HTML or image-based routes.

3. AI Image-Driven Workflows

Representative projects include NanoBanana-PPT-Skills, gpt_image_2_skill, and ppt-image-first.

This route treats each slide as a visual image first, then places the images into PPTX or another container. Its advantage is a high level of visual completion, especially for covers, social media graphics, visual proposals, and communication-oriented content.

The problem is poor editability. A page is essentially an image. If you later need to change a title, replace a paragraph, or move an icon, you may need to regenerate it. It is good for “it needs to look good,” but not for “the client will revise it repeatedly.”

4. MCP / Protocol Layer

Representative projects include Office-PowerPoint-MCP-Server and PPTAgent.

These tools do not necessarily generate a complete PPT directly. Instead, they give AI an interface for operating PowerPoint. After connecting through MCP, the model can read, modify, and write .pptx files.

This route fits workflows where a PPT file already exists and AI is needed to help revise it. Examples include batch format changes, rearranging pages based on feedback, or asking the model to check whether each slide matches the goal. PPTAgent emphasizes reflective generation, meaning it checks back after generating each slide. That direction is useful for reducing the “AI PPT feels rough” problem.

5. Integrated Design Platforms

Representative projects include open-design and docsagent.

These projects go beyond PPT generation itself. open-design is more like a local-first design platform that can generate prototypes, slides, images, and videos, with support for multiple export formats. docsagent is not a PPT tool, but it can index and chat with local documents, making it useful as a material organization layer before generating PPT.

If your need is not a one-off PPT, but a fuller workflow from materials, design, and prototypes to delivery, this type of platform is more worth watching.

Skill Metadata

Star counts come from the original crawl result on 2026-05-15. They are only useful as a popularity reference. Before actual use, open the repositories again to confirm maintenance status, README, and LICENSE.

Skill	Author	Links	Star	Language	Route
frontend-slides	@zarazhangrui	GitHub: zarazhangrui/frontend-slides	17,530	Shell	HTML web presentation
guizang-ppt-skill	@op7418 (Guizang)	Site article: guizang-ppt-skill GitHub: op7418/guizang-ppt-skill	8,832	HTML	HTML web presentation
html-ppt-skill	@lewislulu	GitHub: lewislulu/html-ppt-skill	3,834	HTML/CSS/JS	HTML web presentation
mckinsey-pptx	@seulee26	GitHub: seulee26/mckinsey-pptx	426	Python	Native PPTX
ppt-agent-skills	@sunbigfly	GitHub: sunbigfly/ppt-agent-skills	714	Python	Native PPTX
claude-office-skills	@tfriedel	GitHub: tfriedel/claude-office-skills	631	Python	Native PPTX
ppt-master	@hugohe3	GitHub: hugohe3/ppt-master	16,626	Python	Native PPTX
NanoBanana-PPT-Skills	@op7418 (Guizang)	GitHub: op7418/NanoBanana-PPT-Skills	2,668	Python	AI image-driven
gpt_image_2_skill	@wuyoscar	GitHub: wuyoscar/gpt_image_2_skill	2,102	Python	AI image-driven
ppt-image-first	@NyxTides	GitHub: NyxTides/ppt-image-first	799	Python	AI image-driven
Office-PowerPoint-MCP-Server	@GongRzhe	GitHub: GongRzhe/Office-PowerPoint-MCP-Server	1,708	Python	MCP / protocol layer
PPTAgent	@icip-cas	GitHub: icip-cas/PPTAgent	4,354	Python	MCP / protocol layer
open-design	@nexu-io	Site article: open-design GitHub: nexu-io/open-design	40,822	TypeScript	Integrated design platform
docsagent	@docsagent	GitHub: docsagent/docsagent	687	TypeScript	Integrated design platform

How to Choose

If the client needs to continue editing, prioritize the native PPTX route, especially ppt-master, mckinsey-pptx, and ppt-agent-skills.

If you are presenting yourself and visual expression matters more than later editing, prioritize the HTML route, especially frontend-slides, guizang-ppt-skill, and html-ppt-skill.

If the goal is a poster-like, cover-like, or shareable visual, prioritize the image route, such as ppt-image-first, gpt_image_2_skill, and NanoBanana-PPT-Skills.

If you already have a PPT file and only want AI to help read, edit, and rearrange it, look at the MCP route.

For explicit scenarios such as academic talks, marketing, translation, or compressing long reports into slides, you can also look for vertical Skills instead of forcing a general-purpose PPT generator to do everything.

Final Notes

Open source projects should not be judged by Star count alone. Before actual use, confirm three things:

Whether the LICENSE allows your use case.
Whether the generated output meets delivery requirements, especially editability.
Whether the cost is acceptable, including model calls, image generation, large-context models, and possible cloud service fees.

These tools change quickly. Star counts will change, and project maintenance status will change too. But the selection logic is relatively stable: decide the delivery format first, then look at specific tools. Whether a PPT is for speaking, editing, or viewing often narrows the choices by more than half.

24 Claude Code Tips: Plan Mode, Rewind, CLAUDE.md, Skills, Agents, and Plugins

Fri, 08 May 2026 08:54:14 +0800

Claude Code is not just a chat box. It is closer to a coding Agent that can enter a project directory, read and write files, run commands, and maintain context.

If you only throw a requirement at it and wait for code, problems appear quickly: unclear plans, repeated permission prompts, growing context, unsatisfactory output, no clear rollback path, and no persistent place for project rules.

Here is a set of common operations for developers getting started with Claude Code.

Start Inside the Project Directory

Claude Code works best when launched inside the project directory, not from a random terminal location.

Create a folder as the project directory, enter it, open a command line, and start Claude Code:

claude

When first entering a project, if Claude Code asks whether to trust the current folder, confirm before continuing. This lets it read files, create files, and run later operations around the current project.

A simple practice task is to ask it to create a photographer portfolio website. The task is visual enough to inspect, and it also lets you practice file generation, command execution, rewind, and later refactoring.

Use Plan Mode First

For more complex tasks, Claude Code may enter plan mode. Plan mode is meant to discuss requirements and break down steps before you approve execution.

After it writes a plan, you usually see options like:

Approve the plan and automatically allow future edit tools.
Approve the plan, but require manual approval for later edits.
Pause and continue discussing the plan with Claude Code.

If the task is clear, approve and continue. If it is not clear yet, ask it to refine the plan, such as page style, tech stack, directory structure, interactions, and acceptance criteria.

Plan mode reduces rework. If an Agent starts directly, it may quickly generate many files; if the direction is wrong, later changes can get messy.

Switch Modes With Shift + Tab

In Claude Code, Shift + Tab can switch between working modes. A common use is entering plan mode or switching into an auto-approve-edit mode.

Suggested habits:

New projects, new features, major changes: start in plan mode.
Small edits and clear fixes: execute directly.
Deletion, bulk replacement, dependency installation: keep manual approval.

In plan mode, Claude Code may ask project-detail questions. Use arrow keys to choose and Enter to confirm. After submitting feedback, it updates the plan.

Do Not Open All Permissions Blindly

When Claude Code runs commands, edits files, or starts programs, it may request permission.

Common choices include:

Allow only this time.
Allow this command type for the current session.
Reject or pause.

For local preview, dev server startup, or file inspection, approve as needed. But do not permanently use a mode that auto-approves all permissions just to save clicks.

Full automation is only suitable when the task is low-risk, clearly understood, and the project already has Git backups. For daily use, keep human approval for deletion, overwriting folders, dependency installation, networking, commits, and scripts.

Run Local Commands in Terminal Mode

Claude Code can enter a terminal-command mode to run local commands.

For example, after generating a page, you can open an HTML file with:

`1`	`start index.html`

start is a Windows command for opening a file, followed by the filename. This is faster than finding the file manually.

Terminal mode is useful for:

Opening generated pages.
Listing directory contents.
Starting local development servers.
Running tests or builds.

Still, be careful with high-risk commands such as recursive deletion, moving directories, bulk overwrites, and system environment changes.

Rewind When the Result Goes Wrong

If the page or code produced by Claude Code is not what you want, and each correction makes it worse, rewind early.

Rewind can return code or conversation to a previous point. Common options include:

Rewind both code and conversation.
Rewind only conversation.
Rewind only code.
Compress earlier content into a summary.
Cancel.

When the direction is clearly wrong, it is usually better to rewind both code and conversation. That returns context and files to a cleaner state together.

Note that Claude Code rewind usually only covers files it created or changed through built-in tools. Files created through external commands may not be fully rewindable. Important projects should still use Git.

Write Long Prompts in an Editor

Do not squeeze complex requirements into one input line.

If the system supports editing a long prompt in a text editor, open the editor, write the requirement clearly, save it, and then send it to Claude Code.

Long prompts should include:

The goal.
The tech stack.
What not to do.
Which files must be kept.
How to verify completion.
Page or feature acceptance criteria.

For example, if you want Claude Code to refactor a plain HTML page into a more modern stack, do not just say “refactor it.” Explain component structure, visual preservation, responsive layout, and ask it to run a build check.

Restore Sessions After Exit

If you need to quit Claude Code midway, exit normally. Later, return to the same project directory and start again:

claude

If previous records do not appear directly, use history-related commands to view and load recent sessions.

This is useful for continuing interrupted work. But do not treat session history as the only memory. Project rules, tech stack, common commands, and notes should live in project files.

Use CLAUDE.md for Project Rules

CLAUDE.md is an important memory file for Claude Code. It usually sits at the project root and tells Claude Code project rules, tech stack, directory structure, and collaboration constraints.

You can ask Claude Code to initialize it:

/init

CLAUDE.md is good for:

Project goals.
Tech stack.
Common start, test, and build commands.
Directory notes.
Code style.
Forbidden actions.
Commit and deployment rules.

During each conversation, Claude Code can use these rules as part of the context. Think of it as a project manual.

A simple test is to add a clear rule into CLAUDE.md, then ask Claude Code something. If its answer follows the rule, it has read the project memory.

Reference Files With @

Typing @ in the input box lets you select files or Agents and add them to the current context.

This is useful when you want Claude Code to:

Read a config file.
Modify a specific page.
Continue based on CLAUDE.md or another document.
Only inspect a specific file instead of guessing the whole project.

Compared with copying file contents into the input box, @ references are clearer and less error-prone.

View and Compress Context

After a long conversation, context grows. When it gets too long, the model may slow down or start ignoring earlier details.

Use:

`1`	`/context`

If context is long, compress history:

`1`	`/compact`

If the result is still poor, consider clearing the current context:

/clear

After clearing, Claude Code can still understand part of the project through files, CLAUDE.md, and the current directory, but it will not keep the full conversation history.

A practical habit: start a new chat after a task is done, write project rules into CLAUDE.md, and do not let temporary discussion grow forever in one chat.

Skills: Turn Repeated Work Into Instructions

Skills are reusable task instructions for Claude Code. They are not one-off prompts, but packaged workflows.

For example, if you often generate weekly reports, create a weekly-report Skill that defines:

Required input.
Output format.
Tone and structure.
What must be preserved.
What must not be invented.

Skills usually contain name, description, and detailed instructions. Once installed in the global Skills directory, Claude Code can recognize and load them for related tasks.

Good Skill candidates include:

Weekly reports.
Code review templates.
Document cleanup.
Image batch processing.
Fixed-format articles.
Project initialization flows.

If you repeatedly copy the same prompt, consider turning it into a Skill.

Agents: Delegate Subtasks to Independent Helpers

Agents are different from Skills.

A Skill is more like an instruction manual. An Agent is more like an independent helper that can work outside the main conversation and return results.

The value of Agents is context isolation. For code inspection, you can create a read-only Agent that only reads the project and outputs a report, without modifying files. This avoids polluting the main conversation and lowers risk.

When creating an Agent, consider:

Project-level or user-level Agent.
Whether Claude Code should generate the config.
Which tools are allowed.
Which model to use.
Whether memory should be saved.
Whether the Agent prompt is clear enough.

For code-audit Agents, give read-only permissions first. Let it output a report, then decide in the main conversation whether to change code.

Plugins: Package Skills, Agents, MCP, and Hooks

Plugins are more complete capability packages. They may include:

Skills
Agents
MCP
Hooks

Compared with installing one Skill, a plugin is better for a full capability set. For example, a frontend design plugin may package visual rules, layout habits, component preferences, and related Agents together.

When installing a plugin, you may choose:

Install to the user directory, effective for all projects.
Install to the project directory, shareable with the project.
Install to a local project directory, effective only on your computer.

Use the user directory for personal common capabilities, the project directory for team conventions, and local project install for temporary testing.

Plugins Can Improve Specific Tasks

For frontend page generation, plugins can be more stable than raw prompts.

For example, for “make a photographer portfolio website,” a plain prompt may generate an acceptable page. If you explicitly use a frontend design plugin, the structure, visual hierarchy, spacing, colors, and overall finish are often better.

This does not mean plugins replace human taste. A better workflow is to let the plugin generate a stronger first draft, then refine details manually.

A More Stable Claude Code Workflow

Putting these tips together gives a steadier workflow:

Start claude inside the project directory.
Discuss requirements in plan mode first.
Confirm tech stack and acceptance criteria before approving the plan.
Keep manual approval for high-risk actions.
Use terminal mode for local preview and tests.
Rewind early when the result goes off track.
Write project rules into CLAUDE.md.
Check and compress context during long chats.
Turn repeated workflows into Skills.
Delegate inspection, research, and analysis to read-only Agents.
Use plugins for domain-specific tasks.
Always keep Git checkpoints for important projects.

This is much more stable than simply sending one requirement and waiting for generation.

Summary

Claude Code efficiency does not come only from model capability. It also comes from workflow control.

Plan mode sets direction, permission approval controls risk, rewind reduces rework, CLAUDE.md stores project rules, /context, /compact, and /clear manage context, Skills reuse fixed workflows, Agents isolate complex subtasks, and plugins package complete capabilities.

The best way to use Claude Code is to let it move tasks forward inside clear boundaries, not to hand the entire project to it at once.

Awesome Codex Skills: A Community Catalog for Extending Codex CLI

Thu, 07 May 2026 20:19:15 +0800

ComposioHQ’s awesome-codex-skills is a community catalog for Codex CLI skills. Its value is not another pile of prompt templates, but a way to package repeatable workflows into installable, reusable, and maintainable Skills.

If you already use Codex as part of daily development, this kind of repository is immediately useful: rules, commands, reference materials, and operating steps that you used to explain again and again can be written down once, then reused whenever the matching Skill is invoked.

What This Repository Solves

Codex Skills can be understood as specialized work modes for Codex CLI. A normal prompt is good for one temporary instruction; a Skill is better for something you want to reuse over time.

For example, you may often need to:

generate commit messages in a fixed format;
look up a specific family of API documentation;
run project-specific test and deployment commands;
rewrite articles, translate docs, or organize notes according to team rules;
call external tools for repetitive development tasks.

Typing these instructions every time quickly becomes overhead. A Skill puts the rules into a standalone directory. The core is usually a SKILL.md file, sometimes accompanied by scripts, templates, reference documents, or assets. When Codex is triggered, it reads the instructions and follows the workflow described there.

How It Differs From a Prompt

A prompt is more like a one-off instruction: “do this task this way.” A Skill is closer to a small operating manual: “whenever this class of task appears, work in this way.”

Its main advantages are:

Reusable: common workflows no longer need copy-and-paste setup.
Reviewable: skill files are usually local Markdown files that can be opened, edited, and versioned.
Extensible: complex skills can include scripts, templates, and references, not just natural language instructions.

That is why catalogs like awesome-codex-skills are useful: they help you discover existing skills, then adapt them to your own workflow.

Installation and Use

The repository provides an installation script and also supports manual installation. A typical flow is:

1
2
3

git clone https://github.com/ComposioHQ/awesome-codex-skills.git
cd awesome-codex-skills
python install.py

If you only want to try a few skills, read the SKILL.md in each skill directory first. Check what it reads, what scripts it may run, what files it may edit, and whether the defaults fit your local environment.

After installation, Codex can match skills when the task calls for them, or you can name a skill explicitly. For long-term use, the most practical approach is often to install a community skill first, then rewrite the instructions around your own project conventions.

Which Skills Are Worth Watching

The most valuable skills are not necessarily the ones with the flashiest names. They are the ones that reliably remove repeated work.

I would first look at:

Development workflow skills: review, testing, commits, releases, dependency checks.
Documentation skills: rewriting, translation, summarization, structured organization.
Tool integration skills: connecting Codex to external services, APIs, and CLI tools.
Project convention skills: encoding team rules, directory structure, naming conventions, and deployment steps.

If a skill merely wraps a single sentence prompt, it has limited value. If it can connect research, judgment, execution, verification, and output into a stable workflow, it is worth keeping.

What to Watch Out For

Community skills are convenient, but they should not be treated as black boxes. This is especially true for Skills that include scripts. Before installing one, check:

what SKILL.md asks Codex to do;
whether it includes scripts that access the network, read or write files, or call external services;
whether the default paths, commands, and permissions fit your machine.

A Skill expands what Codex can do. Written well, it makes Codex feel more like a teammate who knows your project. Written carelessly, it can bring unsuitable rules into your workflow. The best pattern is not to install many skills, but to keep a small set, tune them carefully, and maintain them over time.

My Take

awesome-codex-skills is worth bookmarking, especially if you already use Codex CLI for real development, documentation, or automation work. It is not an official capability by itself; it is a community entry point for finding and adapting reusable workflows.

For heavy users, the point of Codex Skills is not simply helping AI remember more. It is helping AI make fewer detours on repeated tasks. Writing rules as Skills turns temporary instructions into reusable working infrastructure.

CC Switch: A desktop tool for managing Claude Code, Codex, Gemini CLI, and OpenClaw in one place

Wed, 06 May 2026 09:03:08 +0800

CC Switch is a desktop management tool for heavy AI coding users. The problem it tries to solve is straightforward: many people now use Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw at the same time, but each tool has its own configuration format, Provider syntax, MCP setup, and Skills management method.

When you only use one tool, manually editing configuration files is still tolerable. Once several tools are mixed together, plus official accounts, third-party APIs, relay services, local models, and shared team configuration, editing JSON, TOML, and .env files by hand quickly becomes tedious.

CC Switch is positioned as a way to pull these scattered configurations into one cross-platform desktop app.

What problem does it solve

Modern AI coding tools increasingly feel like “development colleagues inside the command line”, but their ecosystems are still not fully unified.

Common pain points include:

Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw all use different configuration formats.
Switching API Providers requires repeated configuration-file edits.
MCP servers are configured repeatedly across different tools.
Prompt files such as CLAUDE.md, AGENTS.md, and GEMINI.md are hard to maintain consistently.
Skills installation, sync, backup, and removal lack a single central entry point.
Switching between multiple accounts, relays, and model services can easily become confusing.
Once a manually edited configuration file breaks, troubleshooting is costly.

The idea behind CC Switch is to stop forcing users to remember every tool’s configuration details, and instead use one unified interface to manage Providers, MCP, Prompts, Skills, Sessions, and proxies.

Supported tools

The README lists five core supported targets:

Claude Code
Codex
Gemini CLI
OpenCode
OpenClaw

These tools are similar in positioning: all center on AI coding, Agent workflows, and command-line collaboration. But their configuration systems differ, and the value of CC Switch lies in wrapping those differences.

For people who often compare different AI coding tools, this is much easier than manually opening configuration files every time.

Provider management

The first layer of CC Switch is Provider management.

It includes more than 50 Provider presets. The README mentions directions such as AWS Bedrock, NVIDIA NIM, and various community relays. Users can copy an API key, import it with one click, and then switch from the interface.

The practical points include:

Add Providers with one click.
Reorder Providers by dragging.
Quickly switch from the system tray.
Import and export Providers.
Sync some common Providers across multiple apps.

For many people, this feature alone is already attractive. In daily AI coding work, the problem is often not “I do not know how to use the model”, but “which tool, endpoint, and account should this key use today”.

Local proxy and failover

Besides writing configuration files, CC Switch also provides a local proxy mode.

The focus of this capability is:

Hot-switching Providers.
Format conversion.
Automatic failover.
Circuit breakers.
Provider health checks.
Request correction.

In simple terms, it does not only write configuration into target tools. It can also add a local proxy layer in the middle, so different tools access model services through the proxy.

This is useful for users with multiple Providers: if one service is down, switch to another; if one model is expensive, move to a cheaper one; if a request format is incompatible, adapt it through the proxy layer.

MCP, Prompts, and Skills

The second important layer of CC Switch is unified management for MCP, Prompts, and Skills.

MCP

It provides a unified MCP panel for managing MCP servers across multiple apps, with support for bidirectional sync and Deep Link import.

This is practical for users already working with MCP. Once there are many MCP servers, configuration easily becomes scattered across different clients. A unified panel reduces duplicate configuration and makes migration easier.

Prompts

The Prompts section supports Markdown editing and can sync corresponding files across different tools, such as:

CLAUDE.md
AGENTS.md
GEMINI.md

These files are essentially project manuals for Agents. Unified management makes it easier to maintain team rules, project conventions, and global prompts.

Skills

Skills can be installed with one click from GitHub repositories or ZIP files. Custom repository management, symbolic links, and file copying are also supported.

If you use tools such as Claude Code, Codex, and OpenClaw at the same time, Skills can easily turn into scattered files across different directories. CC Switch centralizes them and reduces maintenance cost.

Sessions and workspace

The README also mentions Session Manager and Workspace features.

It can browse, search, and restore session history from multiple apps. For people who use AI coding tools over a long period, session management is genuinely important: many valuable contexts, debugging trails, and solution comparisons are buried in old conversations.

It also provides a Workspace editor for OpenClaw, allowing users to edit agent files such as AGENTS.md and SOUL.md with Markdown preview.

This shows that CC Switch is not just a small “key switching” utility. It is expanding toward an AI Agent workstation.

Cloud sync and data storage

CC Switch supports syncing Provider data through Dropbox, OneDrive, iCloud, NAS, or WebDAV.

Local data storage is also clearly defined:

Database: ~/.cc-switch/cc-switch.db
Local settings: ~/.cc-switch/settings.json
Automatic backups: ~/.cc-switch/backups/
Skills: ~/.cc-switch/skills/
Skill backups: ~/.cc-switch/skill-backups/

It uses SQLite as the main data source and emphasizes atomic writes and automatic backups, with the goal of avoiding configuration-file corruption during switching or writing.

This design matters for heavy users. If the configuration management tool itself writes a bad configuration, every AI coding tool can be affected.

Installation

CC Switch is a cross-platform desktop app built on Tauri 2.

The approximate system requirements are:

Windows: Windows 10 or later
macOS: macOS 12 Monterey or later
Linux: Ubuntu 22.04+, Debian 11+, Fedora 34+, and other mainstream distributions

Windows users can download the .msi installer or a portable compressed package.

macOS users can install it with Homebrew:

1
2

brew tap farion1231/ccswitch
brew install --cask cc-switch

To update:

`1`	`brew upgrade --cask cc-switch`

Linux users can choose .deb, .rpm, or AppImage. Arch Linux users can also install it through paru -S cc-switch-bin.

As of May 6, 2026, the repository page shows the latest release as CC Switch v3.14.1, published on April 23, 2026.

Tech stack

Judging from the repository structure, CC Switch is a typical Tauri desktop app:

Frontend: React 18, TypeScript, Vite, TailwindCSS, TanStack Query, shadcn/ui
Backend: Tauri 2, Rust, SQLite, Tokio
Testing: Vitest, MSW, Testing Library

Core design patterns include:

SQLite as the Single Source of Truth.
JSON for device-level local settings.
Writing into target tools’ live config during switching.
Filling current Provider edits back from live config.
Atomic writes using temporary files plus rename.
Locked database connections to avoid concurrent write issues.

This architecture suggests the project is not a simple script, but a desktop tool designed for long-term use.

Who it is for

CC Switch suits these users:

People who use Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw together.
People who frequently switch between official accounts, third-party relays, local models, or team Providers.
Users already making heavy use of MCP.
Teams that want to maintain CLAUDE.md, AGENTS.md, and GEMINI.md in one place.
Users who often install, test, and migrate Skills.
People who want to view session history and usage across different tools.

If you only use one AI coding tool, rely on official login, and rarely touch Providers, MCP, or Skills, its value may not be obvious.

But if you have already entered a “many tools, many accounts, many Providers, many projects” state, it can remove a lot of repetitive configuration work.

What to watch out for

Tools like this are convenient, but they also need clear boundaries.

First, it manages configuration for multiple AI CLIs, so users should be sure they trust the tool and its write logic.

Second, API keys, relay endpoints, and MCP servers are all sensitive configuration. Before enabling cloud sync, make sure the sync folder and WebDAV service are secure and trustworthy.

Third, after switching Providers, most tools still need the terminal or CLI to be restarted before changes take effect. The README mentions that Claude Code supports hot-switching Provider data, but other tools usually still require a restart.

Fourth, when switching back to official login, it is better to add the official provider according to the project instructions and then rerun the corresponding tool’s login flow.

Summary

The value of CC Switch is not that it creates yet another AI coding tool. Its value is that it acknowledges a reality: the AI coding ecosystem has entered a stage where multiple tools coexist.

Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw each have their own configuration systems, while MCP, Skills, Prompts, and Providers are expanding quickly. Continuing to edit configuration files by hand will eventually become a burden.

CC Switch pulls these pieces into one desktop app, making it easier to switch Providers, sync MCP, manage Skills, maintain prompt files, and view sessions. For heavy AI coding users, tools like this may move from “optional utility” to “daily infrastructure”.

References

farion1231/cc-switch

Codex App Beginner Guide: Installation, Sandbox, Parallel Tasks, Skills, and MCP

Wed, 06 May 2026 08:41:17 +0800

Codex App can be understood as a task workspace for AI coding. It is not a traditional IDE, nor just a chat window. It brings multitasking, project management, sandbox permissions, Git, cloud execution, plugins, Skills, MCP, and automation into one interface.

If you already use Codex CLI, Claude Code, Cursor, or other coding agents, the most interesting part of Codex App is that it turns “running multiple agents in parallel” into a clearer desktop workflow.

What Codex App Is Good For

The core value of Codex App is not answering questions, but letting AI continuously execute tasks inside a project directory:

Edit code, run commands, and start development servers.
Manage multiple projects and multiple tasks.
Run long tasks locally or in the cloud.
Call plugins, Skills, and MCP for extended capabilities.
Manage changes through Git, worktree, and PR workflows.

OpenAI also positions Codex App as an interface for managing multiple coding agents. It is suitable for people who need to advance several coding tasks at once, especially frontend pages, scripts, small apps, documentation, and automation workflows.

Preparation Before Installation

Before using Codex App, it is best to prepare three basic tools:

Git
Node.js
VS Code or your preferred IDE

Codex App supports macOS and Windows. After installation, sign in with your ChatGPT account. On first launch, you can choose your main usage scenario, such as programming or daily work. Codex will preload some plugins and Skills based on your choices, and you can adjust them later in settings and the plugin marketplace.

The main features on Windows and macOS are broadly similar, but some computer automation capabilities may depend on platform and plugin support. Use whatever your current version actually displays.

Interface Structure: Projects, Tasks, and Chats

Codex App uses a classic three-column layout:

Left: projects, tasks, chat history, plugins, and automation entry points.
Middle: current chat window.
Right: files, browser, terminal, run results, and other panels.

A project usually corresponds to a local folder. You can open multiple chats inside the same project, or open several projects at once so different agents can work in parallel.

The task list shows different states:

Running: the agent is still executing.
Waiting for approval: you need to confirm permissions, networking, dependency installation, or a high-risk action.
Completed: the task has finished, and you can inspect the result or continue asking.

This is more intuitive than switching between multiple terminal windows, and it is better suited to managing several AI tasks at once.

Sandbox and Permission Control

Codex App’s permission system is built around the sandbox. By default, the current project folder becomes the agent’s main workspace.

Common permission boundaries include:

It can read and modify files inside the project directory.
It cannot freely modify files outside the project by default.
Networking or high-risk commands are restricted by default.
When elevated access is needed, it asks the user for approval.

A practical mode is “auto review”: low-risk actions are automatically allowed, while high-risk actions are still confirmed by the user. This reduces frequent pop-ups while keeping dangerous operations from happening silently.

“Full access” should be enabled cautiously. It is suitable when you know exactly what the agent needs to do and the project already has Git backups and important files have separate backups. It is not recommended as a long-term daily default.

Context, Models, and Quotas

Codex App shows the current chat’s context usage. The longer the conversation and the more history it contains, the more context the model needs to process.

Useful habits:

Start a new chat after finishing a task.
Long chats can be compressed manually, but do not treat compression as perfect memory.
For complex tasks, clearly state goals, boundaries, and acceptance criteria.
Do not dump large irrelevant logs, errors, or files into a chat all at once.

For model selection, adjust reasoning strength according to task complexity. Simple edits, writing, and repetitive tasks do not always need the strongest model. Architecture migration, difficult bugs, and cross-file refactors are better suited to stronger models.

If the interface has a fast mode, remember that it usually consumes more quota. Use it when speed matters, but not as a daily default.

Image Generation and Multimodal Inputs

Codex App can accept images and files as context, and can call image generation in suitable scenarios.

This is useful for frontend and content projects. For example, you can ask Codex to:

Fix page styles based on screenshots.
Replace unsuitable images in a webpage.
Generate product images, carousel images, or page assets.
Point out what needs to be changed from a UI screenshot.

A more efficient approach is not to say only “make it look better”, but to use screenshots and point to concrete problems, such as “the spacing in this card is too large”, “this image does not match the service scene”, or “make the map area clearer”.

Steer: Correcting Direction During Execution

Steer can be understood as taking over the direction during execution. If the agent has already started but you realize it misunderstood the direction, you should not always wait for it to finish before correcting it.

You can use steering to insert a new instruction into the current execution flow and make Codex correct course.

Good use cases for Steer include:

The agent misunderstood the requirement.
The generated page style is clearly wrong.
The current plan is too expensive or heavy.
You need to add a key constraint temporarily.

In general, keep the default queued behavior and manually use Steer only when intervention is needed. This avoids disrupting normal tasks while still letting you pull the direction back at key moments.

Plan Mode and Built-In Browser

For complex tasks, start with plan mode. In plan mode, Codex does not immediately modify code. It first outputs a plan and may ask key questions with cards.

Tasks suitable for plan mode include:

Framework migration, such as moving a React project to Next.js.
Large refactors.
Features involving databases, authentication, or deployment.
Requirements where you have not decided the technical path.

The right panel in Codex App can open a built-in browser to preview the local development server. You can annotate the page and let Codex modify a specific UI location. This “look at the page, click the position, ask AI to change it” workflow is often better for frontend debugging than pure text descriptions.

Git, IDE, and Code Rollback

Codex App is not a full IDE. It can view code and add annotations, but handwritten editing is still better done in VS Code, Cursor, Windsurf, or another IDE.

Every Codex project should initialize Git early:

Ask Codex to create or check .gitignore.
Commit once after reaching a usable state.
Ensure a clean commit point before each large change.
Roll back with Git if you are not satisfied.

If you roll back only the chat history, the code will not automatically roll back. A safer approach is to return the chat to the right point, then use a Git commit hash to return the code to the corresponding state.

Worktree: Parallel Development in Multiple Directions

git worktree is especially suitable for parallel agents in Codex App.

It creates multiple independent working directories from the same repository, each corresponding to a different branch. This lets different agents work in different folders at the same time without overwriting each other.

Typical usage:

One worktree optimizes the customer review component.
One worktree adjusts store information and map layout.
Merge both tasks back to main after completion.
Remove temporary worktrees after merging.

This is much safer than letting multiple agents modify code in the same directory. If conflicts happen, review and merge them using normal Git workflows.

Cloud Execution Environment

Codex can work not only on your local machine, but also in a cloud environment.

Cloud execution is suitable when:

You are outside and only have a phone.
You want agents to run long tasks in the background.
The code has already been synced to GitHub and Codex needs to modify the remote repository.
You want changes reviewed and merged through PRs.

A typical flow is: push local code to GitHub, let Codex pull the repository in a cloud environment, execute the task, generate changes, then present them as a PR or diff for review.

When continuing local development, remember to pull down the latest remote changes.

Memory System: Write a Good AGENTS.md

New chats do not have complete historical memory by default. Once a project becomes complex, repeatedly explaining the background is inefficient.

The most general solution is to maintain AGENTS.md in the project root. This file can record:

Project goals and main tech stack.
Common commands.
Directory structure.
Code style and naming conventions.
Prohibited actions, such as bulk deleting files.
Test, build, and deployment rules.

You can also ask Codex to read the project and generate a first version of AGENTS.md, then review it manually. For complex projects, this file is worth maintaining.

Global rules should be used carefully. They are suitable for universal safety constraints, such as “do not recursively delete directories” or “confirm before destructive operations”. Do not put project-specific details into global rules, or they will pollute other projects.

Plugins and Automations

Plugins connect Codex to external services such as GitHub, Gmail, Google Drive, databases, and deployment platforms.

Their value is reducing copy and paste. For example, Codex can:

Check star trends for a GitHub repository.
Summarize email content and send it to you.
Run a recurring check.
Write the result as a summary.

Automations are suitable for repeated tasks. For example, checking repository data every Friday afternoon and sending an email report. Simple automation tasks usually do not require the strongest model; a lighter model is enough.

Skills: Turn Workflows Into Reusable Capabilities

Skills are “professional playbooks” for Codex. They are not one-off prompts. They package a task flow, rules, scripts, and notes so Codex can reuse them reliably later.

Common sources include:

Official Skills.
Third-party Skills.
Skills you write yourself.

Good candidates for Skills include:

Turning subtitles into illustrated notes.
Writing weekly reports in a company format.
Batch-processing images or documents.
Fixed-format code reviews.
Project initialization for a specific framework.

If you have copied and pasted the same prompt many times, it is worth turning it into a Skill.

MCP: Connect External Tools and Databases

MCP can be understood as a standardized tool protocol for large models. Through MCP, Codex can call external services to complete more concrete tasks.

For example, after connecting Supabase, Codex can:

Create database tables.
Read database schemas.
Modify backend endpoints.
Submit frontend forms to the database.
Debug problems based on database state.

This is powerful, but permissions matter. Databases, production environments, deployment platforms, and email accounts are high-risk resources. When connecting for the first time, use a test project and a low-privilege account.

Deployment Plugins

Deployment platform plugins can let Codex complete builds and releases directly, such as deploying a frontend project to Netlify.

These plugins are suitable for small websites, prototypes, internal tools, and demo projects. In real use, pay attention to:

Run a local build before deployment.
Do not write environment variables directly into code.
Check whether the page opens normally after publishing.
Keep human review for production projects.

AI can help connect the deployment flow, but deployment permissions should still be managed carefully.

Computer Automation

With supported platforms and plugin environments, Codex can also operate browsers or desktop apps, completing tasks closer to RPA.

Examples:

Open a chat app and prepare a message.
Browse a project board and summarize task status.
Generate an English brief.
Send it to a specified recipient after you confirm.
Turn the flow into a scheduled automation.

These capabilities are imaginative, but they require the strongest safety boundaries. Any operation involving sending messages, sending email, submitting forms, payments, or deleting data should retain human confirmation.

Usage Suggestions

The right way to use Codex App is not to let it fully take over everything at once, but to break tasks down and let it execute efficiently in a controlled environment.

Recommended habits:

Initialize Git for every project.
Use plan mode for complex tasks.
Use worktree for parallel tasks.
Put project rules in AGENTS.md.
Keep human confirmation for high-risk actions.
Turn repeated workflows into Skills or automations.
Validate plugins and MCP in a test environment first.

References

Summary

Codex App is not “one more AI chat window”. Its focus is turning AI coding into a manageable workspace where local projects, cloud tasks, Git, worktree, plugins, Skills, MCP, and automation can connect.

The key to using it well is balancing freedom and control. Small tasks can be handed to Codex boldly. Complex tasks should start with a plan. High-risk actions must be confirmed. Used this way, Codex can become not just a code-writing assistant, but a long-term engineering tool.

mattpocock/skills: A Practical Skill Collection for AI Coding Agents

Fri, 01 May 2026 03:43:20 +0800

mattpocock/skills is a public collection of AI coding agent skills from Matt Pocock.

It is not a full application, nor a new chat client. It is a set of working skills that can be used by AI coding assistants. The idea is practical: break common AI coding problems into small skills that an Agent can call in the right task, instead of relying on one huge prompt every time.

If you often use Claude Code, Codex, Cursor, or similar AI coding tools, this kind of skills collection is worth watching. What really affects the AI coding experience is often not whether the model can write code, but whether it can move through the task in your preferred working style.

What Problem It Solves

AI coding assistants are powerful, but they can easily go wrong.

Common situations include:

Starting code changes before understanding the requirement
Modifying too many files at once
Producing lots of explanation but little useful action
Blindly trying things after errors
Not running tests or checks in time
Ignoring existing project patterns
Introducing unnecessary abstractions to finish a task
Writing code without truly reviewing risks afterward

These problems are not always caused by weak model capability. Often, the workflow is not constrained well enough.

The value of mattpocock/skills is that it turns these common failure modes into reusable operating methods, making the Agent behave more like an experienced engineering collaborator in different scenarios.

What Are Skills

In the AI Agent context, a skill can be understood as a reusable task instruction, working method, or professional workflow.

It does not have to be a code plugin, and it does not always need to call an external service. In many cases, a skill is simply a clear set of rules:

When to use it
What to do first
What not to do
What output is required
How to judge task completion

This is somewhat like a normal prompt template, but the granularity is closer to a task capability.

Normal prompt templates are usually copied and pasted manually by the user. Skills are better as part of an agent toolbox, allowing the Agent to choose the right workflow for the task.

Why Small and Composable Matters

The README emphasizes that these skills are small and composable.

This direction matters.

If one skill tries to handle everything, it quickly becomes a new giant prompt: long, vague, and hard to maintain. The advantage of small skills is clear boundaries.

For example, one skill can focus on:

Planning first
Fixing TypeScript errors
Running tests and fixing based on results
Doing code review
Summarizing project conventions
Improving prompts
Removing unnecessary abstractions

These skills can be combined according to the task. A simple task may need only one skill, while a complex task can chain several together.

This is closer to real engineering work. You do not use the same workflow for every problem; you choose tools according to the situation.

Keeping the Engineer in Control

One important direction of this repository is keeping the engineer in control.

AI coding can easily slide into two extremes.

The first is fully manual. AI only helps write a few lines of code, while all context, planning, and verification still depend on you.

The second is fully hands-off. You throw a task to an Agent, let it change a lot of things, and then face a diff that is hard to review.

Skills help find a more stable middle position.

They let AI take on more repetitive workflow, while still constraining it with rules:

Understand the task before acting
Read relevant files before editing
Keep the modification scope controlled
Report uncertainty
Verify after changes
Do not refactor unrelated code just to show off

This does not weaken AI. It makes AI actions easier for humans to review and take over.

Alignment Problems

The first kind of AI coding failure is often alignment failure.

The user wants a very specific change, but the Agent may understand it as a larger refactor. The user only wants a bug fixed, but it changes styles along the way. The user wants existing architecture to be followed, but it introduces a new pattern.

Skills can help the Agent do several things at the start of a task:

Restate the goal
Identify the impact scope
Recognize existing implementation patterns
Provide a plan
Clarify what will not be done

This step is like an engineer’s self-check before starting work.

If the Agent cannot clearly state the task boundary and starts writing code directly, it is easy for the task to drift.

Feedback Loop Problems

AI should not write code through one-shot generation alone.

In real development, feedback loops matter:

Change a small piece
Run tests or type checks
Read the errors
Fix them
Verify again

Many Agents fail because they skip the middle feedback. They change many things at once and then summarize from intuition that “it should work.”

Skills can make the feedback loop explicit. For example, they can require the Agent to:

Run relevant checks after modification
Read error messages first if checks fail
Avoid blindly changing unrelated files
Re-verify after each round of fixes
Report final verification results

This makes AI coding more like real debugging and less like one-shot writing.

Architecture Control Problems

AI is good at generating abstractions, and also good at over-generating abstractions.

To complete a small requirement, it may create a service layer, helper functions, configuration objects, type wrappers, and adapters, making the code much more complex than the requirement itself.

This is especially dangerous in large projects. AI-generated abstractions often look “professional,” but they may not match existing project style and may increase maintenance cost.

Good skills remind the Agent to:

Prefer existing patterns
Avoid unnecessary new abstractions
Avoid refactoring unrelated areas
Match the change to the size of the task
Understand the code before designing structure

This reduces output that looks engineered but is actually harder to maintain.

Why Review Skills Matter

Writing code and reviewing code are different states.

When an Agent writes code, it usually tends to prove that its implementation works. It may explain why the change should work, but it does not always actively look for risks.

The purpose of a review skill is to switch the Agent’s role:

Find potential bugs
Find behavior regressions
Find missing tests
Find edge cases
Find increased complexity
Find inconsistencies with existing conventions

This matters for AI coding because AI generates code quickly. Without review, users can easily be overwhelmed by large diffs.

A good review output should list issues first, not praise the implementation first. It should help the engineer decide whether the change can be merged.

Difference from Normal Rules Files

Many AI coding tools support rules, instructions, or memory.

These files usually record long-term rules, such as:

Project tech stack
Naming conventions
Test commands
Directories not to modify
Answer style preferences

Skills are more focused on task workflow.

Rules tell the Agent “how to behave in the long term,” while skills tell the Agent “how to execute this kind of task.”

The two work best together.

For example, rules can say the project uses pnpm test, while a review skill requires checking test coverage after changes. Then the Agent knows not only the command, but also when to use it.

Suitable Scenarios

Repositories like mattpocock/skills are suitable for:

Frequent use of AI coding tools
Agents working on real codebases
Reducing out-of-scope AI edits
Making the Agent verify results more actively
Turning your engineering habits into skills
Learning how others design agent workflows
Turning temporary prompts into a maintainable skill collection

If you only occasionally ask AI to write a small function, you may not need to maintain skills.

But if you already treat AI as a long-term development partner, skills become increasingly important. They are like a reusable working method for the Agent.

How to Learn from This Repository

Even if you do not use every skill directly, you can learn several things from this repository.

First, write down failure modes.

Do not only complain when AI makes a mistake. Turn the patterns it often gets wrong into rules, so a skill can prevent them next time.

Second, keep skills short.

One skill should solve one clear problem. The shorter it is, the easier it is to call correctly and maintain.

Third, make output format clear.

If you want the Agent to list a plan first, execute next, and summarize verification results at the end, write that structure clearly. Vague requirements usually produce vague results.

Fourth, keep human handoff points.

A good skill should not let AI run too far alone. When there is uncertainty, expanded impact scope, failing tests, or a product decision, it should stop and explain the situation.

Notes for Use

First, do not turn everything into a skill.

Too many skills make the system complex, and the Agent may not know which one to choose. Start with the highest-frequency and most painful scenarios.

Second, skills need iteration.

The first version of a skill may not be good. Watch how AI actually executes it, then gradually delete, add, and rewrite.

Third, do not let skills replace engineering judgment.

Skills can improve workflow, but they cannot guarantee correct implementation. Tests, review, build checks, and human judgment still matter.

Fourth, pay attention to differences between Agents.

Claude Code, Codex, Cursor, and Copilot support instructions, skills, and rules differently. The same idea can be reused, but the specific format should be adjusted for each tool.

Reference

mattpocock/skills

Final Thought

What makes mattpocock/skills worth watching is not one magic prompt inside it, but the practical AI coding idea it demonstrates: break engineering experience into small skills, then let the Agent combine them by scenario.

As AI coding moves from occasional assistance into daily workflow, skills become important tools for constraining Agents, keeping engineers in control, and improving feedback quality.

Why Does a Codex Skill Exist in the Directory but Still Not Show Up?

Wed, 29 Apr 2026 11:18:00 +0800

This problem was easy to miss: several skills were already placed under ~/.codex/skills, but after opening a new Codex thread, the sidebar still showed only a small subset of them.

At first, it looked like a cache or indexing issue. The real cause was more specific: several SKILL.md files started with a UTF-8 BOM. Codex 0.111.0’s skill loader did not skip that byte sequence, so it misjudged the files as having no valid YAML front matter.

Symptom

The local directory contained these skills:

~/.codex/skills/git-commit-push/SKILL.md
~/.codex/skills/hugo-rsync-deploy/SKILL.md
~/.codex/skills/bilibili-speech-transcriber/SKILL.md
~/.codex/skills/product-cutout-normalize/SKILL.md

But after opening a new thread, the actually exposed skills were only:

1
2

bilibili-speech-transcriber
product-cutout-normalize

In other words, a file existing on disk does not mean the current session can load it successfully. Codex parses the front matter of each SKILL.md first. If parsing fails, that skill is excluded directly.

Investigation

Starting a fresh session with codex exec showed a more direct error. In VS Code or other IDEs, these logs may not be visible:

1
2

failed to load skill C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md: missing YAML frontmatter delimited by ---
failed to load skill C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md: missing YAML frontmatter delimited by ---

Visually, these files seemed to have a normal header:

---
name: post-rewrite
description: ...
---

The real problem was at the byte level.

The beginning of a failing file was:

`1`	`EF-BB-BF-2D-2D-2D`

The beginning of a file that loaded correctly was:

`1`	`2D-2D-2D`

2D-2D-2D is ---. The preceding EF-BB-BF is the UTF-8 BOM.

Cause

In Codex 0.111.0, the skill loader expects the first byte of SKILL.md to be the first - in ---.

If the file starts with a UTF-8 BOM, the actual beginning becomes:

`1`	`BOM + ---`

So the loader thinks the file does not start with the front matter delimiter and reports:

`1`	`missing YAML frontmatter delimited by ---`

The skill content was not wrong, and the directory was not wrong either. A small encoding detail prevented the parser from recognizing the file.

Fix

Convert the affected SKILL.md files to UTF-8 without BOM.

In PowerShell, this can be done like this:

$paths = @(
  'C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md',
  'C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md',
)

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)

foreach ($p in $paths) {
  $text = [IO.File]::ReadAllText($p, [Text.Encoding]::UTF8)
  [IO.File]::WriteAllText($p, $text, $utf8NoBom)
}

After processing, the file header should change from:

`1`	`EF-BB-BF-2D-2D-2D`

to:

`1`	`2D-2D-2D`

Verification

After restarting a Codex session, the visible skills were restored to:

git-commit-push-zh
hugo-rsync-deploy
bilibili-speech-transcriber
product-cutout-normalize

If the sidebar still shows the old list, close the current Codex sidebar or window and reopen the project. The skill list is usually loaded when the session starts, so changes made in the middle of a session may not refresh immediately.

One Last Line

This kind of issue is easy to mistake for “Codex did not re-index” or “the skill was not installed correctly.”

When troubleshooting, check these three things first:

whether SKILL.md is really in the correct directory
whether the file has valid --- front matter at the top
whether the file is UTF-8 without BOM

The key in this case was the third point: the file looked fine, but its first byte was not -, so Codex did not treat it as a valid skill.

What Is the Difference Between ~/.codex/skills and Project .codex/skills in Codex

Wed, 29 Apr 2026 11:08:00 +0800

When organizing Codex skills, people most often get stuck on two questions:

What is the difference between ~/.codex/skills and project/.codex/skills?
Why does a skill exist in the directory but not appear in the current session?

Here is the short version.

The Difference

The simplest way to remember it:

~/.codex/skills is your global skill library
project/.codex/skills is the local skill library for that repository

`~/.codex/skills`

Use it for:

skills you personally reuse across projects
general workflows that are not tied to a specific repository
workflows that clearly belong to your own habits

For example:

post-rewrite
post-translate
git-commit-push
hugo-rsync-deploy
bilibili-speech-transcriber

The key trait of this kind of skill is: it still makes sense outside the current project.

`project/.codex/skills`

Use it for:

workflows that only apply to this repository
rules tightly coupled to the current project structure, scripts, or templates
skills that should be shared by the team

For example:

a publishing workflow specific to this repository
a generation template that only works in this project
automation steps tightly bound to private project scripts

The key trait of this kind of skill is: it stops being meaningful once it leaves this repository.

When to Use Global and When to Use Project Skills

This rule of thumb is enough:

If it is about your personal habits, put it in ~/.codex/skills
If it is about repository rules, put it in project/.codex/skills
If it can be reused across projects, prefer global
If it should be shared by multiple people and evolve with the repository, prefer project-level

The Current Repository

Based on the current state:

your machine has ~/.codex/skills
this repository does not have .codex/skills

So right now, you mainly rely on global skills.

That means workflows such as post-rewrite, post-translate, and git-commit-push are currently more like part of your personal workflow, not something explicitly bundled with this repository.

Why a Skill Exists on Disk but May Not Appear in the Current Session

There are two different things here:

Existing on disk: the skill file exists in a local directory
Exposed to the session: the current session registered it into the available skill list

These are not the same thing.

So this can happen:

a skill already exists under ~/.codex/skills
but it does not appear in the list after /

This usually does not mean the skill is broken. More often, it means: the current session has not re-indexed it.

How to Make a Skill Available in the Current Session

The practical checklist is short.

1. Put It in the Right Directory

Global:

`1`	`~/.codex/skills/<skill-name>/SKILL.md`

Project-level:

`1`	`project/.codex/skills/<skill-name>/SKILL.md`

2. Make the `SKILL.md` Header Recognizable

At minimum, it needs:

---
name: your-skill-name
description: What this skill does
---

3. Open a New Session After Creating or Editing It

In many cases, a skill does not appear because the current session already fixed its available skill list when it started.

So if you create a skill in the middle of a session, it may already exist on disk, but this session may not recognize it.

The most reliable workflow is:

Put the skill in place
End the current session
Re-enter the project
Open a new session
Check whether it appears under /

4. Put Project Skills in Place Before Starting

If you want project/.codex/skills to be recognized more reliably, put those skills into the project before entering the repository and starting the session.

One Last Line

The shortest conclusion is:

~/.codex/skills is your personal skill library
project/.codex/skills is the repository’s local rule library
a skill existing in the directory does not mean the current session will always show it
the most common fix is to put it in the right directory, write a valid SKILL.md, and then start a new session