Agentuity project
Skill agentuity/sdk/packages/skills/skills/agentuity-project
Use when creating, importing, running, building, or deploying an Agentuity app. Covers framework-first project structure, agentuity.json, .env setup, agentuity dev, agentuity build, agentuity deploy, monorepo --dir usage, and deployment bundle inspection.From its SKILL.md
npx -y skills add agentuity/sdk --skill agentuity-projectAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
4.4 KB, as published. Nobody here has run it
Agentuity Project Lifecycle
Agentuity deploys framework apps as they are. Keep the framework's routing, pages, server functions, and config in their normal locations. Agentuity adds project metadata, local environment wiring, build packaging, deployment, and managed services.
Choose Create or Import
Use agentuity create for a new app:
agentuity create --name my-app --framework nextjs
Use agentuity project import for an existing framework app:
agentuity project import --name my-app --confirm
For monorepos, run commands from the app package or pass --dir:
agentuity project import --dir apps/web --name web --confirm
agentuity deploy --dir apps/web
What Agentuity Adds
After create/import, expect these files next to the app's package.json:
| File | Purpose |
|---|---|
agentuity.json | Project, org, region, and deployment metadata |
.env | Local SDK key and linked resource values |
.agentuity/launch.json | Build output contract produced by agentuity build |
The framework still owns dev, build, and route files. Agentuity adds deploy tooling and cloud resource wiring.
Development Loop
Use the framework's normal dev command for everyday framework work. Run through Agentuity when you want the CLI to inject linked project credentials, expose the Agentuity tunnel, or validate the deployed-like environment:
agentuity dev
Read the terminal output for the actual local URL and tunnel URL. Do not invent localhost ports or public deployment URLs.
Build and Deploy
Build locally when you need to inspect packaging:
agentuity build
Check .agentuity/launch.json after a build. It describes the process Agentuity will start after deployment.
Deploy from a linked project:
agentuity deploy
For multiple environments (same code, different cloud projects):
agentuity deploy \
--project-config agentuity.staging.json \
--env .env \
--env .env.staging
--project-config selects the project metadata file (default agentuity.json).
Global --env loads env files in order; later files override earlier keys.
The deploy flow syncs non-Agentuity env values, builds the app, packages the bundle, uploads assets, provisions the deployment, and prints the deployment ID plus URLs.
Existing App Checklist
Before deploying an existing app:
- Run
agentuity project import --validate-only. - Fix any reported framework, package, or build issues.
- Run
agentuity project import --name <name> --confirm. - Run
agentuity build. - Inspect
.agentuity/launch.json. - Run
agentuity deploy.
Working With Services
When adding Agentuity services to app code, import standalone clients in the server-side module that owns the work:
import { KeyValueClient } from '@agentuity/keyvalue';
const kv = new KeyValueClient();
export async function saveDraft(userId: string, draft: string): Promise<void> {
await kv.set('drafts', userId, { draft }, { ttl: 60 * 60 * 24 });
}
For service selection and client examples, use the agentuity-services skill.
For terminal management of resources, use the agentuity-cloud skill.
Common Mistakes
| Mistake | Better approach |
|---|---|
| Moving framework files into Agentuity-owned folders | Keep route and page files where the framework expects them |
| Creating project metadata by hand | Use agentuity create or agentuity project import |
Treating agentuity dev as mandatory | Use it only for CLI env wiring, tunnel output, or deploy-like validation |
| Guessing deployment URLs | Read agentuity deploy output or inspect deployments with the CLI |
| Importing from the repo root in a monorepo | Run from the app package or use --dir |
Useful Docs
- Project structure: https://agentuity.dev/get-started/project-structure
- Import existing app: https://agentuity.dev/get-started/import-existing-app
- Deployment: https://agentuity.dev/reference/cli/deployment
- Build configuration: https://agentuity.dev/reference/cli/build-configuration