AKE Usage Help and Entry Routing
A. Daily Skill Commands (used in conversations)
| Command | Function |
|---|
| Display usage help (this page) |
| Display usage help (identical to ) |
| View the current installation and version status (read-only, no network access) |
| Check for and install AKE updates (explicitly initiated by the user through the deterministic CLI workflow) |
The host passes only the
token to this Skill. The following
,
, and
are
natural-language inputs, not structured parameter routes handled by the host. In case of ambiguity, or if an update may overwrite local customizations, ask the user first; do not decide on their behalf.
B. CLI Installation and Project Initialization (used in a terminal)
| Command | Function |
|---|
npx skills add Shakyae/agent-knowledge-engine@<full commit> --skill ake -g
| Install/update into the user-level Skills directory (Vercel Skills CLI) |
| Initialize the current working directory |
| Initialize a specified directory |
| View installation status while retaining existing knowledge statistics |
| Check for and update the installed Skill (refer to for available arguments) |
Note:
refers to the AKE source code or the project-bundled CLI (
or
node .ake/tools/scripts/ake.mjs …
). Skill installation and linking are handled by the Vercel Skills CLI above. Because
does not advance an installation pinned to a specific commit, use
to update it.
C. Knowledge Management Capabilities
- Automatic Retrieval: At the start of tasks involving implementation, troubleshooting, architecture, or risk-related changes, first retrieve the four knowledge categories: Agent Notes, Defensive Patterns, Postmortems, and Cookbooks.
- Automatic Capture Assessment: After a substantive task is complete and confirmed by the user, assess whether the task produced reusable knowledge worth capturing.
- Manual Assessment of the Current Session: Directly ask AKE to assess whether the current work is worth organizing, without first running the automatic workflow.
- Manual Organization of a Specified Experience: Explicitly request that a particular experience be organized into a candidate; AKE will organize only the scope you specify.
- View Candidates:
node .ake/tools/scripts/ake.mjs candidate list
to view all candidates and their statuses.
- Check Review Status:
node .ake/tools/scripts/ake.mjs candidate show <id>
/ .
- Publishing Authorization Workflow: After an independent reviewer has reviewed a candidate, explicit user authorization is required before running
approve <id> --by <human> --confirm
and . Without authorization, the candidate remains unpublished.
Routing Rules
- or : Output only this help page. A no-argument must not be interpreted as a knowledge-capture task, must not scan the current Session, must not perform automatic retrieval, and must not create a candidate.
- : Execute (read-only). If the current directory does not contain an AKE project, report the error truthfully; do not fall back to another project.
- : Execute the deterministic CLI update workflow in the following order:
- If
resources/ake-source/scripts/ake.mjs
exists within this Skill directory and supports → use it to execute the update;
- Otherwise, if the current directory is an official AKE source checkout ( points to the official repository and has no uncommitted changes) → use
node <checkout>/scripts/ake.mjs update
;
- If neither condition is satisfied → stop and explain why. The model must not construct its own shell, Git, copy, or cleanup commands.
- After a successful update, notify the user: DSH reads from disk whenever it loads/injects a Skill, and old content already injected in this Session will not refresh automatically. Invoke again in a new message; if the old content is still being used, start a new Session. There is no need to restart the entire DSH.
- Before performing anything that may overwrite user customizations or when the installation target cannot be confirmed, ask the user first.
Examples
- → displays only this help page, with no retrieval or capture.
- Run in a project directory → initializes the current directory; run only when initializing a directory elsewhere.
- Use to view version, installation, and update status; use when an update is needed (automatic backup, verification, and rollback on failure).
Differences Between Installation, Initialization, and Daily Use
- Installation: Places the Skill in the user-level Skills directory; performed once per machine/user.
- Initialization: Establishes for a Git project, including the knowledge directory, configuration, and project-local CLI; performed once per project.
- Daily use: Invoke AKE with a specific request, such as
/ake assess whether this experience is worth capturing
, or allow AKE to retrieve/capture knowledge automatically according to the task phase. Entering by itself only displays the help page and does not trigger retrieval or capture. Daily use does not repeat installation or initialization.
AKE knowledge operations
First determine the absolute path of the target project and use the absolute path to the current Skill base directory provided by the Skill loader. The Skill path must not be inferred from the current working directory, target project, or AKE source checkout. If the loading environment does not provide this absolute path, first ask the user to provide or confirm the installed Skill location; do not guess the path.
Project Initialization (as needed)
For the first check, use the following
command to perform a read-only preflight check against the target. Do not treat results from an ordinary shell
process that inherits
environment variables as authorization. The bootstrap clears all
environment variables before checking. The target may be either the root of a standalone Git worktree or a project subdirectory within an existing parent worktree. It initializes only the exact directory specified by the user; it does not migrate upward, create a nested Git repository, or run
. If the result clearly indicates that the target is not a Git worktree, ask the user whether to select or initialize a Git project first. Retry only after the user confirms and the directory has been established by the user as a valid worktree. If Git is missing or the check reports a bare repository or another Git error, do not infer that a new repository can be created; stop and report the reason. A failed check must result in zero writes.
If both
and
.ake/tools/scripts/ake.mjs
are existing files in the target, treat the project as initialized. Do not run bootstrap again or copy or upgrade the configuration/CLI. Bootstrap only safely reads the configuration version and the bundled package metadata and reports whether they differ. It does not execute the project CLI, and the configuration version cannot prove the version of the CLI itself. If the version cannot be determined, explicitly report it as unknown. For an old or unknown-version project CLI, before any write operation ask the user to run the read-only command
node <absolute target path>/.ake/tools/scripts/ake.mjs status --json
and confirm that the returned
exactly equals the target absolute path. The Agent does not automatically execute the existing project CLI or any write command before confirmation. If the project root is incorrect, first create a backup and have the user manually review the migration/merge plan against the current official AKE version. Do not automatically copy, upgrade, or overwrite project CLI files, configuration, or knowledge files. Only after confirmation may the project’s own CLI be used.
If either file is missing, use the offline resource executor bundled with this Skill, without depending on an AKE source checkout or the working directory used at invocation time. First present the plan:
bash
node <absolute path of this Skill base directory>/bootstrap.mjs --dir <absolute target path> --dry-run
If the dry run reports any
, stop and report the conflicting paths; do not apply a partial plan. If there are no conflicts, apply the plan:
bash
node <absolute path of this Skill base directory>/bootstrap.mjs --dir <absolute target path>
Bootstrap invokes the original AKE initializer from the offline resources under
. If those resources are incomplete, it lists the exact missing files and does not write project files. Restore or update the Skill from the AKE source checkout according to the official Skill installation instructions in the README, then retry. Initialization does not install any global Skill or upgrade an existing project CLI.
Program-testable behaviors include Git root validation, dry-run, conflict rejection, offline initialization, and preservation of an existing CLI/configuration. “Ask the user when the target is not a Git repository” is a soft instruction for the Agent and cannot be proven by a script or automated test. Do not describe prompt-based rules as a security boundary.
Before the Task: User-Visible Notification and On-Demand Retrieval
- When a task first enters an AKE trigger phase, whether relevant engineering knowledge retrieval or post-task capture, provide the user with a brief notification before the first AKE CLI operation. Combine multiple consecutive search/candidate commands within the same phase under this notification instead of repeating it for every command.
- For Agent Teams, the Lead/task owner sends the user notification centrally. Members report retrieval/candidate results to the Lead and do not each send separate notifications to the user.
- During a triggered retrieval phase, first state, “I will retrieve AKE project knowledge and use it according to relevance.” Then construct specific keywords based on the module/technology, symptom, or operation and execute
node .ake/tools/scripts/ake.mjs search <terms>
. Retrieve knowledge only when the task is relevant; do not perform empty searches for unrelated tasks.
- Searches cover the four knowledge roots by default: Agent Notes, Defensive Patterns, Postmortems, and Cookbooks. Results must display or explain their category labels. Use when needed, and narrow results with /.
- After a match, read the relevant documents read-only. Assess their scope, status, state, evidence, and whether they still apply to the current code. Do not treat a match as an automatic instruction. The final report must identify the search terms, matched documents/categories, and their applicability. No matches means only “not found,” not that the knowledge does not exist.
After the Task: Assess Whether Knowledge Is Worth Capturing
- Agent Note: A reusable design/implementation decision, important trade-off, or rationale for a change. Write it to
.agents/notes/{proposed,implemented,rejected}/{class}/
according to its lifecycle.
- Defensive Pattern: A repeatable rule or defensive check. Write it to .
- Postmortem: An incident that has occurred, including its impact, timeline, root cause, and safeguards. Write it to .
- Cookbook: Reusable operational steps and validation methods. Write it to .
Create candidates only for evidence-based, reusable new knowledge. For ordinary Q&A, trivial changes, work with no stable lessons, or results already covered by existing documentation, report
AKE · No new knowledge this time
. If potentially valuable new knowledge has been identified but core evidence is insufficient, do not incorrectly report “No new knowledge this time.” Do not create a candidate. Instead, explicitly report “Potential knowledge awaiting evidence,” explain what is missing, and describe how it can be validated. Never fabricate scope, evidence, validation dates, session/event identifiers, or resolution status. Search established knowledge and candidates before creating or revising a target, and prefer revising the genuinely corresponding existing target. Each candidate must correspond to an actually valuable result and be supported by A- or B-level evidence relevant to its core claim. Traceable evidence may consist of direct observations that can be verified within the current session; no additional persisted artifact or ID is required. Select validation appropriate to the claim. Do not claim that tests or checks were run when they were not, and do not require every candidate to have an actual test. State the applicable scope and validation conditions. Before creating or updating a candidate, notify the user:
AKE · Preparing to capture as <category>: <brief topic>
. Use
or
,
, and
; verify the format, target, links, duplicates, scope, evidence, content hash, and target hash item by item.
Independent Review and Publishing Authorization
-
Agent Teams: Prefer an independent reviewer who did not participate in generating the candidate and has suitable domain expertise. Run
review <id> --reviewer ... --verdict <approve|request-changes|reject> --notes ...
using the reviewer’s real name. Do not impersonate another identity. After sending a review request, wait for the reviewer’s actual result. Successful dispatch, tool acceptance, or silence does not mean the review is complete. If the actual result cannot be awaited in the current turn, pause and truthfully inform the user/Lead; do not claim that a review occurred.
-
Single Session: If an independent subagent is available, assign the review to a reviewer who did not participate in generation and wait for the actual result. If no independent reviewer is available, explain that independent review is unavailable and pause until a reviewer is arranged. The author’s self-check may be recorded as supplementary evidence, but it must not be claimed as independent or used as a substitute for the required independent review.
-
Reviewer reports use the
,
, and
labels. Existing CLI verdicts remain
approve|request-changes|reject
:
maps to
;
maps to
if the core claim is supported and all limitations are explicitly recorded in the candidate, or to
if limitations must first be supplemented or clarified;
maps to
or
depending on whether the issues are fixable. Do not use the new labels as CLI verdicts.
-
Evidence grades apply to the candidate’s core claim, not to metadata completeness.
A (strong direct evidence) means source code/diffs related to the claim, actual test logs, reproducible results, or meaningful before/after comparisons; unrelated code or tests cannot support the claim.
B (usable evidence in the current context) means current runtime/system state related to the claim, an actual browser inspection, direct verification by the Session Agent, user confirmation of intent/acceptance, or readable configuration, installation scripts, or system state. B does not require persisted materials, independent evidence files, or session/event IDs, nor does it require turning direct session observations into separate independent corroboration; assess relevance and limitations according to the claim.
C (core evidence missing) means the core claim has no fundamentally relevant evidence, the evidence does not match the claim, or existing evidence contradicts it. A/B evidence can support a relevant core claim. A C-grade core claim must be marked
and mapped to
/
according to whether it is fixable. The absence of a session ID, event number, independent evidence file, or a relevant topic does not itself lower the evidence grade or constitute a
; never fabricate evidence to satisfy fields.
-
If potentially valuable knowledge cannot form a candidate because it has C-level evidence, report “Potential knowledge awaiting evidence,” including the specific gaps and validation path. Do not say “No new knowledge this time.” The message
AKE · No new knowledge this time
is used only when there is genuinely no new, reusable result.
-
After receiving
, automatically revise the candidate at most once and then have the independent reviewer perform one actual re-review. If it still fails on the second review, pause and report the result; do not continue looping. When the CLI records a verdict, preserve the existing candidate status and binding gates.
-
After the reviewer passes, report the candidate and its limitations to the user and wait for explicit authorization to publish. Do not grant automatic authorization by default, and do not run
or
in advance. After receiving explicit authorization, use the existing CLI command
approve <id> --by <human> --confirm
to record the authorization, then run
. The
value is a declaration, not identity authentication. If the user has not authorized publication, keep the candidate unpublished and explain its ID, status, and the reason for waiting.
-
After content is modified or drift is observed, resubmit and re-review the candidate under the existing gates. Publishing must continue to preserve binding validation, drift detection, the ledger, and unknown-result reconciliation. Skill/AGENTS are soft constraints that ordinary file tools can bypass and are not security boundaries.
-
Synthetic regression example, not an observed fact: Suppose the Session Agent actually inspected the button text, background/border,
/
pseudo-element stacking, actual computed styles, and dropdown interactions on the target Tampermonkey page, and the user confirmed those observations; other pages/menu themes were not inspected and were recorded as limitations. Such immediate-context evidence is B-level and does not require persisted screenshots, independent evidence files, or session/event IDs. The expected result is
, mapped to the CLI verdict
. It must not be marked
merely because identifiers or persisted files are missing or other themes remain unverified. If the same candidate actually has no fundamental evidence for these core claims, its grade is C, and it must be marked
and mapped to
/
according to whether it is fixable. This example is a synthetic test vector, not an actual browser inspection or acceptance of Tampermonkey behavior.
Trigger Routing and Boundaries of Continuous Execution
- Apply triggers by phase and execute only the steps applicable to the current phase. A pre-task trigger performs retrieval and applicability assessment only; it does not initiate candidate capture. A post-task trigger first assesses capture value and evidence. When the user explicitly invokes , execute the phase requested by the user without being constrained by the conditions for automatic completion phrases. Continue to duplicate checking, candidate creation/revision, and independent-review requests only when the post-task assessment confirms that the result is evidence-based, reusable, and not already covered. If there is no value, report
AKE · No new knowledge this time
; if evidence is insufficient, report “Potential knowledge awaiting evidence.” Never force candidate creation.
- Execute all applicable steps in the current phase as one continuous run. Do not ask “Should I continue?” between retrieval, applicability assessment, value/evidence assessment, duplicate checking, or qualified-candidate preparation/submission/reviewer requests. Wait only when an actual reviewer response or user publishing authorization is required. If an actual reviewer result cannot be awaited, report that honestly rather than fabricating a result. Existing permissions, security, validation, and status gates for candidate/submit/review/approve/publish are not relaxed by continuous execution.
- Automatic completion-phrase routing applies only to this one additional automatic signal: a substantive engineering task previously occurred, such as implementation, debugging, testing, architecture, or a risk-related change; this Skill was loaded; and the user subsequently explicitly says “validation OK,” “tests passed,” “no issues,” “acceptance passed,” or similar. This condition does not limit explicit invocations or existing applicable knowledge triggers. Ordinary Q&A, explanations, and conversations with no engineering output do not automatically enter the candidate workflow because of a completion phrase. Completion confirmation also does not constitute publishing authorization.
- These message rules are model-level soft constraints, not host-level hard triggers. Ordinary-language messages cannot guarantee automatic loading of this Skill. Explicit may inject it through the host mechanism, but AKE must not claim that it observes every message or guarantees detection of arbitrary completion phrases. If it cannot confirm that the Skill was loaded, say so truthfully.
Common Commands
node .ake/tools/scripts/ake.mjs candidate new --kind <note|defensive-pattern|postmortem|cookbook> --title <title> --author <actual-name> --target <path> --body <file>
node .ake/tools/scripts/ake.mjs candidate submit <id>
node .ake/tools/scripts/ake.mjs candidate check <id>
node .ake/tools/scripts/ake.mjs review <id> --reviewer <actual-reviewer> --verdict <approve|request-changes|reject> --notes <evidence>
; the CLI verdict does not accept PASS labels
- Only after explicit user authorization to publish:
node .ake/tools/scripts/ake.mjs approve <id> --by <human> --confirm
, followed by
User-Visible Final Report
At the end of the task, briefly complete the following report without omitting unverified items:
text
AKE Knowledge Workflow
- Retrieval: <keywords>; matched <category/document and applicability>, or not found
- Capture: <Agent Note | Defensive Pattern | Postmortem | Cookbook + title/target>; if potential knowledge is awaiting evidence, specify the evidence gaps/validation path; write “AKE · No new knowledge this time” only when there is genuinely no new reusable result
- Check/Review: <candidate check result; independent reviewer’s actual result, or independent review unavailable and paused>
- Authorization/Publishing: <published after explicit user authorization, or left unpublished because authorization/review was incomplete, with the reason; candidate status>
- Verification: <commands actually run and their results>
- Risks/Unverified: <remaining items>
Boundaries
AKE is a process and tooling layer, not a security boundary. Ordinary file/shell tools can bypass the workflow; identities cannot be verified, and automatic authorization markers do not prove human authorization or genuine reviewer independence. Publishing applies only to candidates processed through the CLI and performs binding, format, target, and drift checks.