aoa-skills: Reusable Skill Packages and Controlled Execution Workflows for Coding Agents

aoa-skills is a public skill library for coding agents like Codex, focusing on reusable workflows with clear trigger boundaries, explicit contracts, risk documentation, and technical traceability. Its core ideas include "bounded execution" and "technical traceability" to ensure agent behavior is predictable, reviewable, and reproducible in software engineering.

As AI coding agents become prevalent, ensuring their behavior is predictable, reviewable, and reproducible is a key challenge. aoa-skills addresses this by being a structured, reusable controlled workflow library (not random prompts or private scripts). It complements aoa-techniques: aoa-techniques stores reusable engineering practices, while aoa-skills packages these into reviewable workflows. The layered design: technique answers "how to do", skill answers "when, what, how to verify", playbook answers "which skills to combine in which scenario".

Each skill in aoa-skills follows strict structure:

1. Trigger Boundaries: Clear context conditions (input reqs, pre-states, env constraints) to prevent misuse.
2. Explicit Contracts: Input/output specs (format, parameters, output types) for clear expectations.
3. Risk Documentation: Potential risks/side effects for transparency.
4. Verification Guidance: Steps and success criteria for quality assurance.
5. Technical Traceability: Explicit links to underlying techniques for design decision traceability.

The project has a skill maturity model and promotion path (from creation to release via multiple review stages) and standardized release process (version control, changelog, compatibility).

For agents, the runtime path is: pick → inspect → expand → object use (select skill → check details → adapt template → use). For humans:

• Beginners: start with skills/aoa-change-protocol/SKILL.md
• Full skill list: SKILL_INDEX.md
• Runtime path: docs/RUNTIME_PATH.md
• Evaluation: docs/EVALUATION_PATH.md

aoa-skills has a complete toolchain: Directory Structure:

• skills/:规范技能包 & deterministic resources
• .agents/skills/: Codex export layer
• config/: portable export, policies, configs
• generated/: derived content (capsules, drills, evaluation matrices)
• Others: docs/, templates/, schemas/, scripts/, tests/

Validation Scripts:

• scripts/build_catalog.py --check: build & check skill catalog
• scripts/validate_skills.py: validate skill format
• scripts/report_skill_evaluation.py --fail-on-canonical-gaps: report evaluation results
• scripts/report_technique_drift.py: detect drift from aoa-techniques
• scripts/validate_agent_skills.py: validate agent skill config

Daily loop: build_catalog.py → validate_skills.py → build_catalog.py --check

Portability: Portable layer supports deployment across environments (Codex portable layer, local adapter contracts, OpenAI skill extensions). Governance: Trust gate & allowlist (control activation), skill context guard (prevent context pollution), runtime governance layer (monitor execution), trigger evals (verify trigger accuracy). Ecosystem: Part of aoa architecture:

• aoa-techniques: reusable practices
• aoa-skills: controlled execution semantics
• aoa-playbooks: scenario combinations
• aoa-evals: quality claims & validation
• aoa-routing: routing/scheduling
• aoa-agents: role contracts

Applicable Scenarios:

• Reusable Codex workflows
• Controlled change protocol skills
• Test & validation skills
• Architecture/context mapping skills
• Contract & invariant skills
• Thin project overlays (custom skills without core code intrusion)

Not Applicable: Private infrastructure instructions, sensitive info examples, raw project dumps, non-reusable one-time prompts, aoa-techniques' technical knowledge, undocumented scripts, skills that silently expand task scope.

aoa-skills evolves AI-assisted software development from prompt engineering to structured skill engineering. Its focus on bounded execution, traceability, and reviewability provides a reference for building trustworthy AI coding assistants. As AI agents play larger roles in software development, such infrastructure becomes critical—it's not just a tool library but a methodology for balancing automation and control, and building maintainable agent capability systems.