Adaptive Skills

Adaptive Skills is a portable library of micro-skills for AI-assisted work.

It helps agents, teams, and AI-enabled workflows choose the right capability for the task, execute it with discipline, and leave behind outputs that are easier to review, reuse, and improve.

The goal is simple: make AI work less improvised.

Try it in two minutes

Start with one small, low-risk task instead of installing the whole library:

npx skills add nevitonsantana/adaptive-skills --skill workflow

Then ask your agent to use the workflow skill before beginning the task. It should make the goal, scope, proof, and next step explicit. When you are ready, add feature-planning and testing:

npx skills add nevitonsantana/adaptive-skills \
  --skill workflow \
  --skill feature-planning \
  --skill testing

Prefer APM? Use the equivalent path:

apm install nevitonsantana/adaptive-skills \
  --skill workflow \
  --skill feature-planning \
  --skill testing

Tell us what changed, what failed, and whether you would use the skill again in Discussions.

Creator

Adaptive Skills was created and is maintained by Neviton Santana, a Staff/Principal Designer working across product design, complex systems, artificial intelligence, and governed AI-assisted work.

• GitHub — nevitonsantana
• LinkedIn — Neviton Santana

Instead of relying on one large prompt, a fixed agent role, or a vague instruction like "be strategic", Adaptive Skills breaks work into small, explicit capabilities such as planning, testing, debugging, UX critique, observability review, premortem analysis, handoff discipline, and domain-specific reasoning.

Why this exists

AI-assisted work often fails for predictable reasons:

• the agent uses the wrong mode for the problem;
• risks and assumptions stay implicit;
• useful patterns disappear after a thread ends;
• project-specific rules leak into reusable prompts;
• teams cannot tell whether an output was improvised, repeatable, or governed.

Adaptive Skills turns repeated work patterns into small, inspectable assets.

Each skill defines:

• when to use it;
• when not to use it;
• the core moves that should happen;
• optional modules that activate only when needed;
• verification criteria;
• handoff signals and anti-patterns.

This makes skills reusable without turning them into bureaucracy.

What Adaptive Skills is

Adaptive Skills is the micro layer for agentic work.

It does not try to replace product strategy, project management, design systems, or orchestration frameworks. It gives those systems a reusable capability layer: small units of judgment and execution that can be projected into different AI runtimes.

Use it when you want:

• more consistent AI-assisted execution;
• clearer specialist handoffs;
• reusable quality gates;
• better separation between portable practices and project-local rules;
• a governed way to evolve prompts, skills, and operating patterns over time.

How it works

The library is built around Core + Modules + Triggers.

• Core Moves — the few moves that should almost always happen.
• Optional Modules — add-ons that activate only when the context needs them.
• Activation Triggers — simple signals that help choose the right modules without building a rigid mini-engine.

This keeps skills practical: structured enough to be repeatable, flexible enough to adapt to the task.

What is in the repository

Portable skills

Portable skills live flat under /skills as skills/<skill-name>/SKILL.md, conforming to the agentskills.io Skill Collection layout consumed by APM. Each skill carries its domain in the metadata.category field of its frontmatter; see docs/skill-categories.md for the category taxonomy and per-category backlog, and ADR-005 for the rationale.

Current examples include:

• workflow — keep work bounded, explicit, and reviewable;
• feature-planning — turn confirmed intent into an executable slice;
• intent-clarification — make the human-owned outcome, expectations, and critical ambiguity explicit before planning;
• testing — define useful validation instead of shallow confidence;
• debugging — isolate causes before changing code;
• lean-implementation — make the smallest safe change after scope and validation are clear;
• domain-language-alignment — reconcile vocabulary across product, domain, docs, ADRs, and code before implementation;
• ux-writing — improve product language and semantic clarity;
• triad-check — coordinate product, design, and technical reasoning;
• checkpoint-review — pause during execution and decide whether to continue, adjust, or hand off;
• premortem — assume a future failure happened and work backwards before execution begins.

Every category now has at least one published skill. See docs/skill-categories.md for the per-category roster and backlog.

Domain packs

Domain packs live under /domain-packs.

They are intentionally specific, versioned, and reusable, but they are not treated as portable skill truth.

Current domain packs:

• domain-packs/crisis-management
• domain-packs/ai-discovery-agent-experience — experimental five-skill v0.1 pack for entity representation, search foundations, measurement, generative visibility, and agent actionability

Projection layer

The repository keeps the canon in source control and treats agent installs as derived artifacts.

• projections/registry.json defines projection metadata.
• Codex projection is first-class today.
• Claude projection remains selective and availability-based in v0.

Capability graph overlay

Adaptive Skills now includes an experimental capability graph overlay under /capabilities.

This does not replace skills. It adds lightweight metadata for:

• capability composition;
• advisory routing;
• execution depth profiles;
• expected evidence;
• escalation boundaries;
• evolution signals.

Start with:

• docs/capability-model.md
• docs/capability-graph.md
• docs/operational-runtime.md
• docs/execution-modes.md

The overlay is intentionally docs/metadata-first. It is not a runtime engine and does not auto-edit the skill canon.

Evolution layer

Adaptive Skills includes a governed evolution layer so the library can improve without self-rewriting.

It uses:

• observations — real usage signals;
• proposals — reviewable change requests;
• reviews — decisions about whether to change, reinforce, defer, or reject;
• reinforced and no-change as valid healthy outcomes.

The canon never self-rewrites in v1.1. Human review remains part of the evolution loop.

See:

• docs/evolution-layer.md
• evolution/README.md

Repository layout

/docs           -> model, taxonomy, telemetry, integration notes
/skills         -> portable skills by domain
/domain-packs   -> explicit domain-specific packs
/projections    -> projection registry for agent installs
/evolution      -> governed learning artifacts, observations, proposals, reviews
/scripts        -> validation and projection tooling
/templates      -> starter templates for new skills and operational worksheets

Use with or without AletheIA

Adaptive Skills is useful on its own.

Use it without AletheIA when you want:

• reusable execution discipline;
• consistent outputs;
• better specialist handoffs;
• portable skill cards for different AI tools.

Use it with AletheIA when you also want:

• macro framing;
• review gates;
• continuity between rounds;
• structured learning and operational memory.

See:

• docs/aletheia-integration.md
• docs/agent-role-integration.md

Current domains

• Engineering — implementation, contracts, testing, debugging, structural review, domain-language alignment
• Design — UX strategy, critique, provocation, UX writing, and design-system intelligence
• Business — strategic framing and synthesis
• Product — feature value governance and opportunity-tree alignment
• Governance — complexity audits, sunset decisions, and knowledge-boundary checks
• Quality — cross-layer quality review
• Metrics — observable, decision-linked signals
• Cross-functional — triad-style checks for multi-function decisions
• Efficiency — chunking, checkpoints, handoff discipline, and bounded execution patterns
• Planning — intent clarification and premortem analysis before consequential plans or commitments

Quick start

Run the repository checks:

python3 scripts/validate_system_state.py
python3 scripts/validate_skills.py
python3 scripts/validate_evolution.py
python3 scripts/report_projection_status.py
python3 scripts/project_to_codex.py --all --dry-run

Project all enabled skills into a local Codex skill directory:

python3 scripts/project_to_codex.py --all

Project one skill:

python3 scripts/project_to_codex.py --skill premortem

Adopt in another project

Official documentation path

For a public reader, use this order:

1. Overview — start with this README and docs/getting-started/overview.md.
2. Install / consume — use docs/getting-started/installation-guide.md, docs/guides/install-via-apm.md, docs/codex-consumer-setup.md, and docs/claude-consumer-setup.md.
3. Choose a skill — use docs/getting-started/skill-catalog.md, docs/how-to-use-a-skill.md, and docs/skill-categories.md.
4. Understand the model — use docs/skill-model.md, docs/domain-taxonomy.md, and docs/skill-catalog-governance.md.
5. Use with AletheIA — use docs/aletheia-integration.md, docs/agent-role-integration.md, and docs/specification-facilitation.md.
6. Advanced overlays — use docs/capability-model.md, docs/capability-graph.md, docs/operational-runtime.md, and docs/evolution-layer.md.
7. Evidence and decisions — use docs/adr/README.md, docs/_meta/, examples/README.md, and evolution/README.md.

For the complete documentation map, see docs/README.md. The publication-readiness record is docs/official-docs-readiness.md.

Recommended first bundle for a new consumer:

• workflow
• feature-planning
• testing

Add premortem when plans have meaningful cost of failure and can still be changed before execution.

Current status

July 2026

See:

• PROJECT_KANBAN.md
• ROADMAP_EVOLUTIVO.md
• EVOLUTION_BACKLOG.md

Field evidence

Adaptive Skills is domain-agnostic (see docs/adr/ADR-002-domain-agnosticism.md). The library was first validated against the Crisis Monitor project; that case is preserved as labeled field evidence:

• docs/crisis-monitor-case-study.md
• domain-packs/crisis-management/ — first example domain pack (not the canonical pack)
• domain-packs/ai-discovery-agent-experience/ — experimental second pack; five skills are delivered, but field evidence remains incomplete

These domain packs remain bounded evidence rather than portable skill truth. The MoradaHarmoniA scaffold does not become completed field evidence until an authorized, reproducible baseline exists.

License

Apache-2.0