Agent Stack Skills

A practical skill stack for AI-assisted software engineering.

简体中文

This repository is both a Codex skill-only plugin and a collection of standalone Agent Skills for prompt refinement, project discovery, environment setup, implementation safety, testing, review, refactoring, and delivery. Install the plugin once for namespaced discovery, or install individual skills when you only need one workflow.

Skill Catalog

Skill	Purpose	Use when	Main outputs	Depends on
using-agent-stack-skills	Routes requests to the smallest matching plugin workflow.	You want the agent to find and execute a matching skill, or only list skills when explicitly requested.	A selected skill, execution decision, or plugin-scoped recommendation.	The other skills in this repository.
enhance	Refines raw software-engineering requests into grounded, execution-ready prompts.	You explicitly ask to enhance, optimize, sharpen, or rewrite a prompt before implementation, optionally followed by execution.	A concise prompt with confirmed context, scope, constraints, deliverables, acceptance criteria, and material open decisions.	No hard dependency; it adapts to available search and code-intelligence capabilities.
onboard-legacy-project	Coordinates the legacy-project onboarding sequence.	You have just cloned or inherited a project and need the smallest useful onboarding path.	Stage recommendations, RCD decisions, and outputs produced by selected downstream skills.	The three onboarding skills in this repository.
map-legacy-project	Maps architecture, modules, dependencies, APIs, and data models.	You need reliable static project context before running or changing an unfamiliar codebase.	Architecture/dependency SVGs, API and data-model docs, AGENTS.md, and a project-local documentation audit skill.	None.
bootstrap-project-environment	Establishes a reproducible Docker-first development environment.	You need to inventory dependencies, start services, smoke-test the project, or prepare a teammate handoff.	Environment checklist, install/startup logs, smoke-test results, setup guide, and minimal Compose additions when required.	None; it can reuse mapping outputs.
build-legacy-guardrails	Builds a pre-change safety net around risky legacy behavior.	You are preparing to refactor, migrate, or make high-risk changes to an existing project.	Critical-path map, test inventory and gaps, P0 characterization/integration tests, CI configuration, and summary.	None; it can reuse mapping and environment outputs.
run-legacy-change-cycle	Runs a complete, gated change-delivery cycle in a legacy or unfamiliar project.	You want to take a concrete request through requirements, design, implementation, tests, acceptance, documentation sync, and retrospective.	requirement.md, solution.md, summary.md, implementation and test evidence, acceptance records, and synchronized project docs.	No hard dependency; reliable project context and a runnable baseline are expected.

Prompt Refinement

enhance uses the repository capabilities currently available instead of depending on one search provider. It can use semantic search, symbol navigation, or local rg/git grep fallbacks, keeps context bounded, protects credential-bearing configuration, and distinguishes enhance-only, enhance-and-execute, and read-only requests.

Legacy Project Onboarding Stack

onboard-legacy-project
├── map-legacy-project
├── bootstrap-project-environment
└── build-legacy-guardrails

The normal sequence is understanding first, reproducible execution second, and guardrails before risky changes. onboard-legacy-project recommends the smallest useful path and coordinates the selected skills; each downstream skill can also be used independently.

Legacy Project Change Delivery

onboard-legacy-project (when baseline context is missing)
└── run-legacy-change-cycle
    ├── requirements and solution decisions
    ├── implementation and characterization tests
    ├── frontend/backend acceptance
    └── documentation sync and retrospective

run-legacy-change-cycle is the post-onboarding delivery workflow for a concrete change. It works autonomously between five user gates: G0 confirms the current behavior, G1 resolves product boundaries, G2 approves major solution decisions, G3 records the pre-change UI state when applicable, and G4 confirms acceptance in the browser or the project's actual client. It persists resumable evidence under docs/requirements/<feature>/.

Installation

Install the Codex plugin

Register this GitHub repository as a custom marketplace:

codex plugin marketplace add barry166/agent-stack-skills --ref main

Then open Plugins in the Codex app, select Agent Stack Skills, and install the plugin. CLI users can install it with:

codex plugin add agent-stack-skills@agent-stack-skills

Start a new task after installation so Codex can discover the plugin skills. To pin the current stable release, replace main with v1.3.0.

Ask an agent to install a skill

Give your agent the repository and skill path, for example:

Install the map-legacy-project skill from
https://github.com/barry166/agent-stack-skills/tree/main/skills/map-legacy-project

Manual installation

Clone the repository, then copy the skill directories you want into your agent's skill directory:

git clone https://github.com/barry166/agent-stack-skills.git
mkdir -p ~/.codex/skills
cp -R agent-stack-skills/skills/onboard-legacy-project ~/.codex/skills/
cp -R agent-stack-skills/skills/enhance ~/.codex/skills/
cp -R agent-stack-skills/skills/map-legacy-project ~/.codex/skills/
cp -R agent-stack-skills/skills/bootstrap-project-environment ~/.codex/skills/
cp -R agent-stack-skills/skills/build-legacy-guardrails ~/.codex/skills/
cp -R agent-stack-skills/skills/run-legacy-change-cycle ~/.codex/skills/
cp -R agent-stack-skills/skills/using-agent-stack-skills ~/.codex/skills/

Use the equivalent skills directory when your agent runtime stores skills somewhere else. Restart or reload the agent session after installation if it does not discover new skills automatically.

Versioned releases

Stable snapshots are published under GitHub Releases. Pin or download a release when you need reproducible behavior; use main for the latest changes.

Usage

Plugin installs use the agent-stack-skills: namespace:

Use $agent-stack-skills:map-legacy-project to document this repository before we change it.
Use $agent-stack-skills:run-legacy-change-cycle to deliver this legacy-project change through acceptance and documentation sync.
Use $agent-stack-skills:enhance to refine this engineering request without implementing it yet.

Standalone installs continue to use names such as $map-legacy-project and $enhance. You can also describe the outcome and let using-agent-stack-skills select the smallest matching workflow. By default it executes a clear match; requests to list, compare, recommend, analyze, stay read-only, or avoid modification remain non-executing.

Update the plugin

Refresh the GitHub marketplace:

codex plugin marketplace upgrade agent-stack-skills

Refresh or reinstall the plugin in Codex, then start a new task.

Repository Layout

.codex-plugin/plugin.json             # plugin manifest
.agents/plugins/marketplace.json      # GitHub marketplace catalog
assets/                               # plugin presentation assets
skills/<skill-name>/
├── SKILL.md
├── agents/openai.yaml
└── references/                       # optional

The plugin manifest packages every directory under skills/. Each SKILL.md remains the source of truth for that skill, while metadata under agents/ improves discovery and presentation in supported agent runtimes.

Contributing

See CONTRIBUTING.md. Keep each skill focused, document when it should and should not run, and never commit real credentials or environment secrets.

License

Licensed under the MIT License.