# Algorand sources

Use this map when maintaining `build-on-algorand` or `audit-algorand`. Verify
claims against the live source rather than copying large sections into the
skill.

## Smart contracts and the AVM

- [Smart-contract overview](https://dev.algorand.co/concepts/smart-contracts/overview/)
- [Algorand TypeScript language guide](https://dev.algorand.co/concepts/smart-contracts/languages/typescript/)
- [AVM overview](https://dev.algorand.co/concepts/smart-contracts/avm/)
- [Costs and constraints](https://dev.algorand.co/concepts/smart-contracts/costs-constraints/)
- [Resource usage](https://dev.algorand.co/concepts/smart-contracts/resource-usage/)
- [Storage overview](https://dev.algorand.co/concepts/smart-contracts/storage/overview/)
- [Box storage](https://dev.algorand.co/concepts/smart-contracts/storage/box/)
- [Protocol 5.0 release](https://github.com/algorand/go-algorand/releases/tag/v5.0.0-stable)

Review newer protocol releases when refreshing the skill. Keep only changes
that affect application design, compiler output, testing, fees, resources, or
security; do not turn the skill into release notes.

## PuyaTs

Start with the maintained example collections:

- [PuyaTs examples](https://github.com/algorandfoundation/puya-ts/tree/main/examples)
- [Focused devportal examples](https://github.com/algorandfoundation/puya-ts/tree/main/examples/devportal)
- [Type semantics](https://github.com/algorandfoundation/puya-ts/blob/main/docs/src/content/docs/language-guide/types.md)
- [Inner transactions](https://github.com/algorandfoundation/puya-ts/blob/main/docs/src/content/docs/language-guide/itxns.md)
- [Migration guides](https://github.com/algorandfoundation/puya-ts/blob/main/docs/src/content/docs/migration-guides.md)
- [Security policy](https://github.com/algorandfoundation/puya-ts/blob/main/SECURITY.md)

Focused examples currently used by the skill include
[hello world](https://github.com/algorandfoundation/puya-ts/blob/main/examples/hello-world-abi/contract.algo.ts),
[auction](https://github.com/algorandfoundation/puya-ts/blob/main/examples/auction/contract.algo.ts),
[voting](https://github.com/algorandfoundation/puya-ts/blob/main/examples/voting/contract.algo.ts),
[ARC-4 options](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/abimethod_options/contract.algo.ts),
[ARC-4 types](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/arc4_types/contract.algo.ts),
[cross-contract ARC-4 calls](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/arc4_client/contract.algo.ts),
[contract options](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/contract_options/contract.algo.ts),
[events](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/events/contract.algo.ts),
[global state](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/global_state/contract.algo.ts),
[local state](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/local_state/contract.algo.ts),
[boxes](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/box_storage/contract.algo.ts),
[group transactions](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/group_transactions/contract.algo.ts),
[inner transactions](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/inner_transactions/contract.algo.ts),
and [opcode budget](https://github.com/algorandfoundation/puya-ts/blob/main/examples/devportal/op_budget/contract.algo.ts).

Preserve the contract/off-chain TypeScript boundary. Re-check restricted
language behavior, AVM-native types such as `uint64` and `bytes`, reference
semantics, `clone(value)`, storage proxies, and generated ARC-56 output when
PuyaTs changes.

## Security audits

Maintain `audit-algorand` against the current
[Algorand Smart Contract Security Best Practices](https://github.com/algorand-devrel/Smart-Contract-Security-Best-Practices)
guide and its runnable PuyaTs examples. The skill is self-contained and must
not require that guide at runtime. Adapt decision rules, invariants, failure
modes, and tested examples into focused references instead of copying its
chapter structure.

Corroborate protocol and compiler claims with the smart-contract, AVM, PuyaTs,
client, and ARC primary sources in this map. Preserve the audit skill's
TypeScript-only boundary and keep severity separate from confidence.

## Clients and tests

- [TypeScript client-generator guide](https://dev.algorand.co/algokit/client-generator/typescript/)
- [TypeScript unit-testing guide](https://dev.algorand.co/algokit/unit-testing/typescript/overview/)
- [AlgoKit Utils TypeScript examples](https://github.com/algorandfoundation/algokit-utils-ts/tree/docs-staging/examples)
- [Application example](https://github.com/algorandfoundation/algokit-utils-ts/blob/docs-staging/examples/concepts/applications.algo.ts)
- [Transaction example](https://github.com/algorandfoundation/algokit-utils-ts/blob/docs-staging/examples/concepts/transactions.algo.ts)

The AlgoKit Utils examples intentionally use `docs-staging`, which currently
contains the latest documentation examples. Re-check `main` on each update and
switch only after the examples are merged and equivalent or newer.

## Frontend wallets

- [TxnLab use-wallet skill](https://github.com/TxnLab/skills/tree/main/skills/use-wallet)
- [use-wallet-ui](https://github.com/TxnLab/use-wallet-ui)
- [VibeKit starter wallet setup](https://github.com/initlabsai/algorand-starter-fullstack/blob/main/app/src/App.tsx)
- [VibeKit starter generated-client call](https://github.com/initlabsai/algorand-starter-fullstack/blob/main/app/src/components/AppCalls.tsx)

Keep this section minimal because TxnLab's skill is available as an optional
remote catalog. Verify the installed major version, SSR lifecycle, network API,
and signer shape before changing examples.

## ARCs

Use the [ARC repository](https://github.com/algorandfoundation/ARCs/tree/main/ARCs)
and [developer-portal index](https://dev.algorand.co/arc-standards/) for live
status. The selected application and asset standards currently come from:

- [ARC-2](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0002.md), [ARC-3](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0003.md), [ARC-4](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md)
- [ARC-18](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0018.md), [ARC-19](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0019.md), [ARC-20](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0020.md), [ARC-28](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0028.md)
- [ARC-55](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0055.md), [ARC-56](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0056.md), [ARC-69](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0069.md)
- [ARC-72](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0072.md), [ARC-89](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0089.md), and [ARC-200](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0200.md)

ARC-32 belongs only in migration or named compatibility guidance. Exclude
legacy wallet standards and withdrawn standards from the normal selection.
Re-check supersession and adoption before recommending a newer standard.

## x402

- [Algorand x402 overview](https://dev.algorand.co/resources/x402-on-algorand/)
- [GoPlausible facilitator guide](https://facilitator.goplausible.xyz/guide)
- [Algorand x402 library README](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/README.md)
- [Simplified and custom-facilitator example](https://github.com/algorandfoundation/WAD-26-x402-demo)

x402 changes quickly and its documentation quality varies. Keep only an
orientation, distinguish the ecosystem facilitator from a custom facilitator,
and direct the agent to current integration sources.

## Upstream provenance

`build-on-algorand` materially adapts the MIT-licensed
[`algorand-devrel/algorand-agent-skills`](https://github.com/algorand-devrel/algorand-agent-skills)
reviewed at
[`35d7e65be978b14e1777fb37c4a70fa92fe8022e`](https://github.com/algorand-devrel/algorand-agent-skills/commit/35d7e65be978b14e1777fb37c4a70fa92fe8022e).
Preserve `build-on-algorand/ATTRIBUTION.md` while adapted material remains.

# Skill design and review

Use the current [Agent Skills specification](https://agentskills.io/specification)
for the portable format. Use the available `skill-creator` skill for the host's
current authoring and validation workflow. Anthropic's
[Agent Skills engineering guide](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
is the design rationale for progressive disclosure.

## Design for selection and loading

- The frontmatter `name` matches the directory and uses lowercase letters,
  digits, and hyphens.
- The `description` says what the skill does and when it applies. Add an
  exclusion only when it prevents likely misrouting.
- `SKILL.md` contains the shared workflow and decision boundaries. References
  contain details needed only for a particular task.
- Link references directly from `SKILL.md` and keep them one level deep.
- Do not create a reference, script, asset, README, or metadata file without a
  concrete consumer.

## Write for capable agents

Use direct, compact instructions. Preserve the facts, constraints, and failure
modes an agent would not safely infer from the code or task alone. Prefer:

- a short invariant over a broad tutorial;
- a current source example over a copied API manual;
- a decision criterion over an exhaustive checklist;
- a named delegation boundary over overlapping skills;
- a precise warning over historical narrative.

Avoid promotional language, generic coding advice, speculative future
features, and requirements derived from one incidental failure. Examples
should clarify a fragile handoff or non-obvious API shape.

## Review evidence

Review every material claim against the strongest available evidence:

1. shipped implementation, types, and tests for VibeKit behavior;
2. canonical specifications and official release notes for protocols;
3. maintained official documentation;
4. runnable source examples from the relevant version or branch;
5. third-party guides only for the third-party integration they own.

Record intentional branch exceptions and upstream commit SHAs. Avoid hard-coded
statuses, limits, package versions, or command names unless the skill needs
them and the maintenance workflow re-verifies them.

## Review outcome

A good update leaves:

- one clear owner for each workflow;
- no contradiction between related skills or generated project guidance;
- no stale or unpublished API presented as current;
- attribution beside materially adapted content;
- a regenerated bundle and passing validation;
- no unrelated worktree changes.

Behavioral testing is useful when a skill is complex or has demonstrated
misrouting. Do not create eval files by default, and do not use prose matching
as a substitute for testing repository behavior.

# VibeKit sources

Use this map when maintaining `use-vibekit`, `build-on-vibekit`, generated
project guidance, or skill distribution. Local implementation and tests are
the authority for shipped behavior.

## Repository contracts

- `AGENTS.md` — operational rules and required gates
- `docs/CONSTITUTION.md` — the bets the project rests on and how work is judged
- `docs/CONSTITUTION.md` — durable rationale and governance
- `packages/vibekit/src/core/contract.ts` — `ToolDefinition`, `ToolContext`,
  `ToolPlugin`, schemas, and tool flags
- `packages/vibekit/src/core/deployment.ts` — context resolution and
  `executeToolCall`
- `packages/vibekit/src/core/compose/` — write composition and execution
- `packages/vibekit/src/tools/` — canonical tool definitions and exact tool names

Read the public exports and package tests alongside implementation. Do not
teach private imports, alternate handler shapes, or a write path around the
compose engine.

## VibeKit operation

Verify `use-vibekit` against:

- `apps/cli/src/commands/` for `new`, `init`, LocalNet, keystore, dispenser,
  doctor, and generic tool behavior;
- `packages/vibekit/src/signer-keystore/` for daemon signing and account custody;
- `apps/cli/src/config/agents-md.ts` for generated project instructions;
- the project's current `package.json` scripts and generated artifacts;
- MCP tool schemas rather than remembered argument shapes.

The three public starter repositories are:

- [contracts](https://github.com/initlabsai/algorand-starter-contracts)
- [full stack](https://github.com/initlabsai/algorand-starter-fullstack)
- [kitchen sink](https://github.com/initlabsai/algorand-starter-kitchensink)

Use the current starter source to verify direct npm scripts, artifact paths,
client generation, tests, deployment examples, frontend signing, and optional
subscriber behavior. Do not restore AlgoKit CLI or Python instructions from
older templates.

## VibeKit extension development

Verify `build-on-vibekit` against:

- `packages/vibekit/src/mcp/` for the generic MCP adapters;
- `packages/vibekit/examples/` for reference stdio and HTTP deployments;
- `packages/vibekit/src/preset/` for the shared stock tool and plugin mix;
- `packages/vibekit/src/plugins/pera/`, `packages/vibekit/src/plugins/nfd/`, and
  `packages/vibekit/src/plugins/alpha-arcade/` for current plugin patterns;
- package manifests and tests for peer dependencies, output schemas, services,
  network guards, and public exports.

For the protocol boundary, use the official
[MCP 2026-07-28 Streamable HTTP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2026-07-28/basic/transports/streamable-http.mdx)
and [release overview](https://blog.modelcontextprotocol.io/posts/2026-07-28/).
VibeKit's remote guidance targets stateless Streamable HTTP; local clients use
stdio. Re-check the installed MCP package and adapters before updating any
wire-level example.

## Skill delivery

The canonical-to-generated path is:

```text
skills/ -> apps/cli/scripts/bundle-skills.ts
        -> apps/cli/src/skills/bundled.ts
        -> vibekit init / vibekit new
```

The source repository exposes the same canonical tree to local agents through
Git-tracked relative symlinks:

- `.agents/skills -> ../skills` for Codex;
- `.claude/skills -> ../skills` for Claude Code;
- `.grok/skills -> ../skills` for Grok Build.

Keep all three discovery roots as links to the complete canonical tree. Do not
copy canonical content or add agent-specific skills beneath those links.

Verify discovery behavior against the current official documentation for
[Codex](https://developers.openai.com/codex/skills),
[Claude Code](https://code.claude.com/docs/en/skills), and
[Grok Build](https://docs.x.ai/build/features/skills-plugins-marketplaces).
The open Agent Skills standard defines skill contents; each host still defines
its filesystem discovery roots.

Use these files when the distribution surface changes:

- `apps/cli/src/skills/index.ts` — bundled skill selection
- `apps/cli/src/skills/catalogs.ts` — reviewed, SHA-pinned remote catalogs
- `apps/cli/src/utils/tarball.ts` — catalog and starter tarball extraction
- `apps/cli/src/commands/init.ts` — selection and installation
- `apps/cli/src/commands/new.ts` — starter creation followed by initialization
- `apps/cli/test/config.test.ts`, `init.test.ts`, and `catalogs.test.ts` —
  bundle, frontmatter, selection, and pin invariants

Do not copy remote catalogs into `skills/`. Do not point catalog refs at a
branch. Regenerate `bundled.ts` after every canonical skill change and confirm
the generated copy contains current user-authored source changes.